Keyset

Keyset configures and verifies OAuth providers in existing Next.js projects. It detects the project and authentication library, calculates the correct callback URLs, stores credentials in an ignored local environment file, updates the auth configuration idempotently, and checks the real authorization redirect.

It is intended for developers and coding agents that want a repeatable OAuth setup workflow without copying client secrets through chat, logs, or source files.

What Keyset does

For a supported project, Keyset can:

• detect Next.js, Better Auth or Auth.js, the package manager, development port, auth route, environment files, and existing provider configuration;

• calculate authorized JavaScript origins and OAuth redirect URIs;

• create a Google Web OAuth client through a visible Chrome session with --auto;

• import existing Google Web credentials or GitHub OAuth App credentials;

• write credentials to .env.local without printing their values;

• add Google or GitHub to an existing Better Auth/Auth.js configuration while preserving other providers;

• avoid duplicate source changes and duplicate Google clients on repeated runs;

• roll local changes back if post-setup verification fails;

• run static, semantic, and optional runtime verification; and

• expose the same project-aware operations to agents through a local MCP server.

Keyset does not replace Better Auth or Auth.js. It configures their OAuth provider integration and verifies the resulting flow.

Related MCP server: GitHub Integration Hub

Supported surface

See Compatibility for the exact tested matrix and known limits.

Installation

Install from this repository

The packages have not yet been published to the npm registry. Until the first registry release, install and link the CLI from source:

git clone https://github.com/fatih-developer/keyset.git
cd keyset
npm install
npm run build
npm link --workspace=@key-set/cli
keyset --version

The link exposes both keyset and its bundled keyset mcp commands. Uninstall the global source link later with:

npm unlink --global @key-set/cli

Install from npm after the registry release

Once @key-set/cli is published, the normal installation will be:

npm install --global @key-set/cli
keyset --version

The npm scope is public, but publishing requires maintainer access to the @key-set scope. Registry credentials must never be placed in this repository.

Prerequisites

• Node.js 20 or newer;

• an existing Next.js project using Better Auth or Auth.js;

• Google Chrome for keyset setup google --auto;

• access to the Google Cloud project when using automatic Google setup; and

• an ignored .env.local file or a .gitignore rule that covers it.

Set KEYSET_CHROME_PATH when Chrome is installed in a non-standard location.

Quick start: automatic Google OAuth

Run Keyset from the application directory:

cd path/to/your-nextjs-app
keyset inspect
keyset setup google --auto
keyset verify google --runtime

Or target a project explicitly:

keyset setup google --auto --project H:\Project\my-app

The automatic flow works as follows:

1. Keyset inspects the application without executing project code.

2. It opens a normal, isolated Chrome profile at Google Cloud Console.

3. You complete Google login, two-step verification, and Cloud project selection. Keyset never asks for or reads your Google password.

4. Keyset completes the Google Auth Platform application information, audience, contact information, and finish steps. This includes accepting the required Google API Services User Data Policy for the selected project.

5. It creates a Web application OAuth client with the detected local origin and callback URI.

6. It reads the newly created Client ID and Client Secret in memory, writes them to .env.local, and never emits their raw values.

7. It updates the detected Better Auth or Auth.js source when needed.

8. It verifies the resulting configuration. Repeating the command on an already configured project returns already_configured without creating a new client.

For the default Next.js development port, the generated values are:

Authorized JavaScript origin: http://localhost:3000
Redirect URI:               http://localhost:3000/api/auth/callback/google

Pass a deployed origin when both local and production URLs should be registered:

keyset setup google --auto --production-url https://app.example.com

If Google changes the Console UI and Keyset cannot safely finish, it stops before applying newly read credentials, saves a diagnostic screenshot in the system temporary directory, and leaves Chrome available for inspection.

Manual Google setup

Preview the exact values first:

keyset setup google --dry-run

Then import an exported Google Web client JSON file:

keyset setup google --credentials ./client_secret.json

Or supply credentials non-interactively:

keyset setup google \
  --client-id "123456-example.apps.googleusercontent.com" \
  --client-secret "replace-with-the-real-secret"

Avoid command-line flags on shared machines because shell history may retain their values. An exported credential file with restrictive permissions is safer.

Better Auth receives GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET. Auth.js receives AUTH_GOOGLE_ID and AUTH_GOOGLE_SECRET.

GitHub OAuth setup

GitHub provisioning is currently guided. Keyset calculates the homepage and callback URL, then applies credentials from the OAuth App you create:

keyset setup github --dry-run
keyset setup github --client-id "your-client-id" --client-secret "your-client-secret"
keyset verify github

See Providers for the GitHub console steps.

Inspection, diagnostics, and verification

keyset inspect                         # detect project facts
keyset providers                       # list provider capabilities
keyset doctor                          # report actionable findings
keyset verify google                   # static and semantic checks
keyset verify google --runtime         # boot app and inspect OAuth redirect
keyset verify google --json            # machine-readable, redacted output
keyset init                            # create .keyset/config.json if absent

Runtime verification executes the detected project development command on a temporary available port. Use it only for project code you trust. It verifies the authorization redirect structure; it does not log into an end-user Google account or complete the final callback.

Use --project <path> with any project command when the current directory is not the target application.

MCP for coding agents

The local MCP server lets compatible agents request typed OAuth operations instead of reimplementing setup with unrestricted shell commands.

After installing/linking the CLI, register it with a supported client:

keyset mcp install codex
keyset mcp install claude

Preview the configuration change with --dry-run. Existing MCP servers are preserved and real config mutations receive a numbered backup.

The agent workflow is:

inspect_project
→ plan_provider_setup
→ import_credentials
→ setup_provider
→ verify_provider

Available MCP tools are inspect_project, list_providers, plan_provider_setup, import_credentials, setup_provider, doctor, and verify_provider. Only setup_provider changes an application project. MCP responses redact secrets and the server does not expose a generic shell tool.

See MCP and Skills for client and agent setup.

What changes in an application

Depending on the detected adapter, setup may change only:

• .env.local, using the adapter-specific Client ID and Client Secret names;

• the detected Better Auth or Auth.js configuration source; and

• .keyset/config.json when keyset init is explicitly run.

Provider packages do not edit source directly, and auth adapters do not create cloud credentials. Core coordinates these boundaries and rolls back local changes when verification fails.

Security model

• Secrets are wrapped in a redacting value type and are not ordinary CLI/MCP output.

• .env.example is never treated as a credential source.

• Secret-bearing environment files are checked against .gitignore.

• Mutations are constrained to the inspected project root.

• Google automation uses a visible browser; login and 2FA remain under the user's control.

• Diagnostics, test fixtures, release archives, and source must contain no live credentials.

Review Security and the Threat model before using Keyset in security-sensitive automation. Report vulnerabilities privately; never open an issue containing credentials.

Repository structure

Runtime and compatibility fixtures live under examples/ and compatibility/. Architecture and operational documentation lives under docs/.

Development and release checks

npm install
npm run build
npm run typecheck
npm run test
npm run lint
npm run verify
npm run test:packed
node scripts/security/secret-sentinel.mjs
node scripts/security/package-audit.mjs
npm run release:rc

npm run verify runs lint, type checking, tests, and a complete workspace build. test:packed installs generated package archives into an isolated temporary project and exercises the distributed CLI and MCP entry points. release:rc creates ignored, checksummed release archives under release-artifacts/.

Limitations

• Google Cloud Console automation depends on the current Console UI and an installed Chrome browser.

• Google login, 2FA, and project selection intentionally require the user.

• GitHub OAuth App creation is guided rather than browser-automated.

• Frameworks other than Better Auth and Auth.js are not currently supported.

• Production runtime verification is not a substitute for a complete real-user sign-in test.

• npm registry packages are prepared but not published yet.

Documentation

• Installation

• CLI

• Google OAuth

• Better Auth

• Auth.js

• MCP

• Compatibility

• Troubleshooting

• Provider SDK

• Contributing

• Changelog

License

Keyset is available under the MIT License.