@jeffjassky/oauth-host 0.1.0 → 0.3.0

package/README.md

@@ -48,14 +48,22 @@ app.use('/mcp', oauth.protect('contacts.read'), mcpRouter);
 Register each client once — there is no RFC 7591 dynamic client registration:
 
 ```js
+import { CLAUDE_CONNECTOR_REDIRECT_URI, CLAUDE_CODE_REDIRECT_URIS } from '@jeffjassky/oauth-host';
+
 const { clientId, clientSecret } = await oauth.clients.create({
   name: 'Claude',
-  redirectUris: ['<Claude connector callback, from their docs>'],
+  redirectUris: [CLAUDE_CONNECTOR_REDIRECT_URI, ...CLAUDE_CODE_REDIRECT_URIS],
   allowedScopes: ['openid', 'contacts.read'],
   branding: { publisher: 'Anthropic' },
 });   // secret returned once, never again
 ```
 
+The callbacks ship as constants because `create()` compares them byte-for-byte
+and retyping one out of a vendor's docs is the most typo-prone step in the setup.
+ChatGPT's current callback is per-connector and therefore not a constant — copy
+it from its setup screen. See
+[Vendor callback URLs](https://jeffjassky.github.io/oauth-host/guide/mcp#vendor-callback-urls).
+
 Or let Claude and ChatGPT register themselves with a [client ID metadata
 document](https://jeffjassky.github.io/oauth-host/guide/cimd) — their
 `client_id` is an `https://` URL serving a JSON description of themselves, and

package/dist/index.cjs

@@ -29,9 +29,11 @@ function clientSchema() {
     {
       clientId: { type: String, required: true, unique: true },
       name: { type: String, required: true },
-      // `public` exists for CIMD clients, which hold no secret and are bound by
-      // PKCE instead. The enum was written with this widening in mind, so it
-      // was one member rather than a migration.
+      // `public` is a client that holds no secret and is bound by PKCE instead.
+      // Two ways in and they are independent: a CIMD row is written public, and
+      // `clients.create({ type: 'public' })` registers one by hand. The enum was
+      // written with this widening in mind, so it was one member rather than a
+      // migration.
       type: { type: String, enum: ["confidential", "public"], default: "confidential" },
       // How the row got here. A `cimd` row is re-derived from the client's own
       // metadata document, so this is what tells the re-fetch path which fields
@@ -500,6 +502,7 @@ function resolveConfig(config) {
   }
   const store = rateLimits.store ?? memoryStore();
   const normalizedMount = `/${String(mountPath).replace(/^\/+|\/+$/g, "")}`;
+  const indexes = { ready: false };
   const ctx = {
     models,
     issuer,
@@ -531,6 +534,11 @@ function resolveConfig(config) {
     cors: { tokenEndpoint: cors.tokenEndpoint ?? false, origins: cors.origins ?? [] },
     clockSkewMs,
     cimd: resolveCimd(clientIdMetadata, scopeIndex),
+    indexes,
+    async syncIndexes() {
+      await syncModelIndexes(models);
+      indexes.ready = true;
+    },
     logger,
     track,
     async audit(entry) {
@@ -1358,6 +1366,15 @@ function assertResources(ctx, input) {
   }
   return [...input];
 }
+function assertClientType(value) {
+  if (value === void 0) return "confidential";
+  if (value !== "confidential" && value !== "public") {
+    throw new TypeError(
+      `oauth-host: client type must be 'confidential' or 'public' (got ${JSON.stringify(value)})`
+    );
+  }
+  return value;
+}
 function assertName(value) {
   if (typeof value !== "string" || !value.trim()) {
     throw new TypeError("oauth-host: a client needs a non-empty `name` \u2014 it is what the consent screen shows");
@@ -1379,35 +1396,38 @@ async function revokeTokensMatching(ctx, filter) {
   return res.modifiedCount ?? 0;
 }
 function createClientsApi(ctx) {
+  async function create(spec) {
+    if (!spec || typeof spec !== "object") {
+      throw new TypeError("oauth-host: clients.create(spec) requires a spec object");
+    }
+    const name = assertName(spec.name);
+    const type = assertClientType(spec.type);
+    const redirectUris = assertRedirectUris(spec.redirectUris);
+    const allowedScopes = assertScopes(ctx, spec.allowedScopes);
+    const allowedResources = assertResources(ctx, spec.allowedResources);
+    const clientId = spec.clientId ?? generateClientId();
+    const clientSecret = type === "confidential" ? generateClientSecret() : void 0;
+    const doc = await ctx.models.Client.create({
+      clientId,
+      name,
+      type,
+      registration: "manual",
+      trusted: Boolean(spec.trusted),
+      // Only the digest is stored. `clientSecret` below is the only time the
+      // raw value exists outside the caller's variable. Empty for a public
+      // client, which is the same shape a CIMD row is written with.
+      secrets: clientSecret ? [{ hash: sha256(clientSecret), label: "initial", createdAt: /* @__PURE__ */ new Date() }] : [],
+      redirectUris,
+      allowedScopes,
+      allowedResources,
+      branding: spec.branding ?? {},
+      status: "active"
+    });
+    await ctx.audit({ type: "oauth.client_created", actor: "admin", clientId, meta: { type } });
+    return clientSecret ? { client: toPublicClient(doc), clientId, type: "confidential", clientSecret } : { client: toPublicClient(doc), clientId, type: "public" };
+  }
   return {
-    async create(spec) {
-      if (!spec || typeof spec !== "object") {
-        throw new TypeError("oauth-host: clients.create(spec) requires a spec object");
-      }
-      const name = assertName(spec.name);
-      const redirectUris = assertRedirectUris(spec.redirectUris);
-      const allowedScopes = assertScopes(ctx, spec.allowedScopes);
-      const allowedResources = assertResources(ctx, spec.allowedResources);
-      const clientId = spec.clientId ?? generateClientId();
-      const clientSecret = generateClientSecret();
-      const doc = await ctx.models.Client.create({
-        clientId,
-        name,
-        type: "confidential",
-        registration: "manual",
-        trusted: Boolean(spec.trusted),
-        // Only the digest is stored. `clientSecret` below is the only time the
-        // raw value exists outside the caller's variable.
-        secrets: [{ hash: sha256(clientSecret), label: "initial", createdAt: /* @__PURE__ */ new Date() }],
-        redirectUris,
-        allowedScopes,
-        allowedResources,
-        branding: spec.branding ?? {},
-        status: "active"
-      });
-      await ctx.audit({ type: "oauth.client_created", actor: "admin", clientId });
-      return { client: toPublicClient(doc), clientId, clientSecret };
-    },
+    create,
     async rotateSecret(clientId, opts = {}) {
       const doc = await ctx.models.Client.findOne({ clientId });
       if (!doc) throw notFound(clientId);
@@ -1436,7 +1456,7 @@ function createClientsApi(ctx) {
         clientId,
         meta: { retireAfter, retiresAt }
       });
-      return { client: toPublicClient(doc), clientId, clientSecret };
+      return { client: toPublicClient(doc), clientId, type: "confidential", clientSecret };
     },
     async update(clientId, patch) {
       const doc = await ctx.models.Client.findOne({ clientId });
@@ -2480,8 +2500,17 @@ function createOAuthRouter(ctx) {
   const ipKey = (req) => req.ip ?? "unknown";
   const clientKey = (req) => clientIdFromRequest(req) ?? ipKey(req);
   const cors = corsMiddleware(ctx);
+  const requireIndexes = w((_req, _res, next) => {
+    if (ctx.indexes.ready) return next();
+    throw new OAuthError(
+      503,
+      "server_error",
+      "This authorization server is not ready: `syncIndexes()` has not resolved yet. Await `oauth.syncIndexes()` at boot, before mounting the routers."
+    );
+  });
   router.get(
     "/authorize",
+    requireIndexes,
     rateLimit(ctx, "authorize", ipKey),
     w(async (req, res) => {
       let validated;
@@ -2540,6 +2569,7 @@ function createOAuthRouter(ctx) {
   router.post(
     "/token",
     cors,
+    requireIndexes,
     form,
     rateLimit(ctx, "token", clientKey),
     w(async (req, res) => {
@@ -2644,6 +2674,7 @@ function createOAuthRouter(ctx) {
   );
   router.post(
     "/consent/:requestId",
+    requireIndexes,
     rateLimit(ctx, "consent", ipKey),
     w(async (req, res) => {
       const user = await requireUser(ctx, req);
@@ -2745,6 +2776,16 @@ function corsMiddleware(ctx) {
   };
 }
 
+// src/server/vendors.ts
+var CLAUDE_CONNECTOR_REDIRECT_URI = "https://claude.ai/api/mcp/auth_callback";
+var CLAUDE_CODE_REDIRECT_URIS = [
+  "http://localhost/callback",
+  "http://127.0.0.1/callback"
+];
+var CHATGPT_LEGACY_REDIRECT_URI = "https://chatgpt.com/connector_platform_oauth_redirect";
+var CHATGPT_CONNECTOR_REDIRECT_URI_PATTERN = "https://chatgpt.com/connector/oauth/{callback_id}";
+var CIMD_ALLOWED_HOSTS = ["claude.ai", "chatgpt.com"];
+
 // src/server/index.ts
 function createOAuthHost(config) {
   const ctx = resolveConfig(config);
@@ -2768,13 +2809,35 @@ function createOAuthHost(config) {
      * stops one user holding two live grants for the same client, and mongoose
      * builds indexes in the background — a cold database will happily serve
      * the write that violates it first. See standards/traps.md #3.
+     *
+     * Resolving this is also what flips `ready` and un-gates `/authorize`,
+     * `POST /consent/:requestId` and `POST /token`.
+     */
+    syncIndexes: () => ctx.syncIndexes(),
+    /**
+     * Has `syncIndexes()` resolved?
+     *
+     * A boolean, not a promise, and the difference is the failure mode. A
+     * promise would have to exist from construction, so a host that never calls
+     * `syncIndexes()` would await it forever — a boot-order mistake turning into
+     * an unexplained hang with no message. A boolean is plainly `false`, cannot
+     * be awaited by accident, and is backed by three routes that say what is
+     * wrong by name. Gate a mount on it, or simply
+     * `await oauth.syncIndexes()` first, which is the same thing said directly.
      */
-    syncIndexes: () => syncModelIndexes(ctx.models),
+    get ready() {
+      return ctx.indexes.ready;
+    },
     /** Escape hatch. Prefer the APIs above; these carry no invariants. */
     models: ctx.models
   };
 }
 
+exports.CHATGPT_CONNECTOR_REDIRECT_URI_PATTERN = CHATGPT_CONNECTOR_REDIRECT_URI_PATTERN;
+exports.CHATGPT_LEGACY_REDIRECT_URI = CHATGPT_LEGACY_REDIRECT_URI;
+exports.CIMD_ALLOWED_HOSTS = CIMD_ALLOWED_HOSTS;
+exports.CLAUDE_CODE_REDIRECT_URIS = CLAUDE_CODE_REDIRECT_URIS;
+exports.CLAUDE_CONNECTOR_REDIRECT_URI = CLAUDE_CONNECTOR_REDIRECT_URI;
 exports.OAuthError = OAuthError;
 exports.RedirectableAuthError = RedirectableAuthError;
 exports.UnredirectableError = UnredirectableError;