@jeffjassky/oauth-host 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffjassky/oauth-host",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "OAuth 2.1 + OIDC authorization server for Express/Mongoose apps.",
   "license": "MIT",
   "author": "Jeff Jassky <jeff@jeffjassky.com>",
@@ -36,7 +36,7 @@
   },
   "files": [
     "dist",
-    "types",
+    "types/index.d.ts",
     "README.md",
     "LICENSE"
   ],

package/types/index.d.ts

@@ -400,9 +400,13 @@ export interface OAuthClientDoc {
   name: string;
   /**
    * `public` clients hold no secret and authenticate with `client_id` alone —
-   * PKCE is the binding that stands in for it. Only CIMD registrations are
-   * public today; a `confidential` client can never downgrade itself by
-   * omitting its secret.
+   * PKCE is the binding that stands in for it. A `confidential` client can
+   * never downgrade itself by omitting its secret.
+   *
+   * Orthogonal to `registration`: a CIMD row is always public, but a public row
+   * is not always CIMD. `clients.create({ type: 'public' })` registers one by
+   * hand, which is the only path open to a client that wants PKCE-only and
+   * publishes no metadata document (Codex CLI).
    */
   type: 'confidential' | 'public';
   /**
@@ -574,16 +578,65 @@ export interface CreateClientSpec {
   trusted?: boolean;
   /** Supply a fixed id for a re-provisioned client. Generated when omitted. */
   clientId?: string;
+  /**
+   * How this client authenticates at `/token`. **Defaults to `confidential`**,
+   * so an existing caller is unaffected.
+   *
+   * `public` generates no secret at all: the registration is `client_id` plus
+   * PKCE, `secrets` is empty, and `rotateSecret()` on it throws. Register one
+   * for a client that takes a `client_id` and nothing else — Codex CLI's MCP
+   * login has `oauth_client_id` and no `oauth_client_secret` field — and cannot
+   * use CIMD because it publishes no metadata document.
+   */
+  type?: 'confidential' | 'public';
 }
 
-export interface CreatedClient {
+/** What `clients.create({ type: 'confidential' })` and `rotateSecret()` return. */
+export interface CreatedConfidentialClient {
   client: PublicClient;
   clientId: string;
+  type: 'confidential';
   /** Returned once. Only its SHA-256 is stored; there is no way to read it back. */
   clientSecret: string;
 }
 
+/**
+ * What `clients.create({ type: 'public' })` returns.
+ *
+ * `clientSecret` is declared as `?: undefined` rather than omitted so that
+ * `created.clientSecret` still type-checks against the union below — and lands
+ * as `string | undefined`, which is what stops a provisioning script printing
+ * the word `undefined` into somebody's connector setup screen.
+ */
+export interface CreatedPublicClient {
+  client: PublicClient;
+  clientId: string;
+  type: 'public';
+  clientSecret?: undefined;
+}
+
+/**
+ * Discriminated on `type`, not a single interface with an optional secret.
+ *
+ * The alternative — widening `clientSecret` to `string | undefined` on one
+ * shape — reads as source-compatible and is not: `const s: string =
+ * created.clientSecret` stops compiling either way. The difference is what
+ * happens to the code that does not annotate. With an optional field a
+ * provisioning script keeps compiling and prints `undefined`; with a union the
+ * caller has to say which kind of registration it asked for before it can reach
+ * the secret at all.
+ */
+export type CreatedClient = CreatedConfidentialClient | CreatedPublicClient;
+
 export interface ClientsApi {
+  /**
+   * The overloads exist so the default path keeps its precise type. A spec with
+   * no `type` (or `type: 'confidential'`) returns a `clientSecret: string`
+   * exactly as before; only a caller that asked for `public`, or that passes a
+   * spec whose `type` is not known statically, has to narrow.
+   */
+  create(spec: CreateClientSpec & { type: 'public' }): Promise<CreatedPublicClient>;
+  create(spec: CreateClientSpec & { type?: 'confidential' }): Promise<CreatedConfidentialClient>;
   create(spec: CreateClientSpec): Promise<CreatedClient>;
   /**
    * Issue a second valid secret and retire the current one after `retireAfter`
@@ -591,9 +644,10 @@ export interface ClientsApi {
    * deployable without downtime.
    *
    * Throws on a **public** client. There is no secret to rotate, and returning
-   * one would hand the caller a credential the token endpoint refuses.
+   * one would hand the caller a credential the token endpoint refuses — which
+   * is also why the return type is the confidential member alone.
    */
-  rotateSecret(clientId: string, opts?: { retireAfter?: number; label?: string }): Promise<CreatedClient>;
+  rotateSecret(clientId: string, opts?: { retireAfter?: number; label?: string }): Promise<CreatedConfidentialClient>;
   update(clientId: string, patch: Partial<Omit<CreateClientSpec, 'clientId'>>): Promise<PublicClient>;
   list(query?: { status?: 'active' | 'disabled'; limit?: number; skip?: number }): Promise<{ items: PublicClient[]; limit: number }>;
   get(clientId: string): Promise<PublicClient | null>;

package/types/test-d.ts

@@ -1,320 +0,0 @@
-/**
- * Compile-only exercise of the public declarations. Never executed — `tsc
- * --noEmit` failing here means the .d.ts files drifted from the source.
- *
- * These declarations are hand-written and the SOURCE IMPORTS THEM, so most
- * drift now fails in `src/` first. This file still earns its place: it is the
- * only thing that checks the surface from OUTSIDE, the way a host consumes it —
- * a type the source never happens to reference can still be wrong here.
- *
- * Hand-written types rot within a day. On featureboard this file immediately
- * caught that `types/` was missing FOUR features added the same afternoon.
- * Every exported symbol must appear below. See standards/traps.md #9.
- */
-import type {
-  ClaimsAdapter,
-  ClientBranding,
-  ClientIdMetadataConfig,
-  ClientSecretRecord,
-  ClientsApi,
-  ContextsApi,
-  CreateClientSpec,
-  CreatedClient,
-  CreateOAuthHostConfig,
-  GrantContext,
-  GrantContextAdapter,
-  GrantSummary,
-  GrantsApi,
-  LoadUser,
-  Logger,
-  ModelNames,
-  OAuthAuditDoc,
-  OAuthClientDoc,
-  OAuthCodeDoc,
-  OAuthError,
-  OAuthEvent,
-  OAuthGrantDoc,
-  OAuthHostInstance,
-  OAuthHostRouters,
-  OAuthKeyDoc,
-  OAuthModels,
-  OAuthRequestContext,
-  OAuthRequestDoc,
-  OAuthTokenDoc,
-  PackageUser,
-  ProtectOptions,
-  PublicClient,
-  RateLimitConfig,
-  RateLimitRule,
-  RateLimitStore,
-  ResolveUser,
-  ResourceSpec,
-  ScopeSpec,
-  SigningConfig,
-  SigningKeySpec,
-  TtlConfig,
-  UserAdapter,
-  UserId,
-  UsersApi,
-} from './index.js';
-
-declare const oauth: OAuthHostInstance;
-
-// ---------------------------------------------------------------------------
-// The degenerate case from plans/build-plan.md §0. If this ever stops
-// compiling as written, the config layer grew a required key the paper test
-// does not pay for.
-// ---------------------------------------------------------------------------
-const minimal: CreateOAuthHostConfig = {
-  issuer: 'https://api.example.com',
-  resources: [{ id: 'https://api.example.com/mcp', label: 'MCP server' }],
-  scopes: [
-    { id: 'openid', label: 'Sign you in', oidc: true },
-    { id: 'contacts.read', label: 'Read your contacts', description: 'Names and emails.' },
-    { id: 'contacts.write', label: 'Create and edit contacts', sensitive: true },
-  ],
-  consentUrl: '/settings/authorize',
-};
-
-// Strings are shorthand for `{ id, label: id }` — §0.3.
-const shorthandScopes: CreateOAuthHostConfig = {
-  ...minimal,
-  scopes: ['openid', 'profile', 'email'],
-};
-
-// `defaultScopes` is optional and is plain scope ids — deliberately NOT a
-// `ScopeSpec[]`, so it cannot be mistaken for a second catalog.
-const withDefaultScopes: CreateOAuthHostConfig = {
-  ...minimal,
-  defaultScopes: ['openid', 'contacts.read'],
-};
-
-// ---------------------------------------------------------------------------
-// Adapters, both forms and both directions.
-// ---------------------------------------------------------------------------
-const withFn: CreateOAuthHostConfig = {
-  ...minimal,
-  resolveUser: () => ({ id: 'abc', email: 'a@b.c', displayName: null }),
-};
-const withAdapter: CreateOAuthHostConfig = {
-  ...minimal,
-  userAdapter: { resolveUser: () => null } satisfies UserAdapter,
-};
-// The second inbound direction. `/userinfo` and the id_token are reached with
-// no host session, so `resolveUser` alone cannot serve profile/email claims.
-const withLoad: CreateOAuthHostConfig = {
-  ...minimal,
-  loadUser: async (id: UserId) => ({ id, email: 'a@b.c', displayName: 'A' }),
-};
-const bothOnAdapter: CreateOAuthHostConfig = {
-  ...minimal,
-  userAdapter: {
-    resolveUser: () => null,
-    loadUser: (id) => ({ id }),
-  } satisfies UserAdapter,
-};
-declare const load: LoadUser;
-void load;
-// Signed-out must be expressible — `/authorize` is a route a signed-out user
-// lands on directly.
-const anon: CreateOAuthHostConfig = { ...minimal, resolveUser: () => null };
-// And async, for a host whose session lookup hits a store.
-const asyncUser: CreateOAuthHostConfig = {
-  ...minimal,
-  resolveUser: async () => null,
-};
-
-const contextAdapter: GrantContextAdapter = {
-  list: (_user, { client, scopes }) => [
-    { id: 'org_1', label: client.name, description: scopes.join(' ') } satisfies GrantContext,
-  ],
-  verify: async (_user, contextId) => contextId.length > 0,
-};
-
-const claims: ClaimsAdapter = (user, { scopes, contextId, client }) => ({
-  plan: 'pro',
-  seen: [user.id, scopes.length, contextId, client.clientId],
-});
-
-const tenanted: CreateOAuthHostConfig = {
-  ...minimal,
-  grantContext: contextAdapter,
-  claims,
-  logger: {} satisfies Logger,
-  track: (event: OAuthEvent) => void event.type,
-};
-
-// ---------------------------------------------------------------------------
-// Every remaining config key, so a rename in `src/` cannot pass silently.
-// ---------------------------------------------------------------------------
-const tuned: CreateOAuthHostConfig = {
-  ...minimal,
-  mountPath: '/oauth',
-  loginUrl: '/login',
-  returnParam: 'next',
-  ttl: {
-    code: 60,
-    accessToken: 3600,
-    refreshToken: 60 * 86_400,
-    refreshAbsolute: 180 * 86_400,
-    authorizationRequest: 600,
-  } satisfies TtlConfig,
-  subjectMode: 'pairwise',
-  pairwiseSalt: 'a-permanent-secret',
-  signing: {
-    autoGenerate: true,
-    keys: [{ kid: 'k1', privateKeyPem: '-----BEGIN PRIVATE KEY-----', alg: 'ES256' } satisfies SigningKeySpec],
-  } satisfies SigningConfig,
-  rateLimits: {
-    token: { max: 60, windowMs: 60_000 } satisfies RateLimitRule,
-    authorize: false,
-    consent: { max: 10, windowMs: 1_000 },
-    store: { hit: async () => ({ count: 1, resetAt: Date.now() }) } satisfies RateLimitStore,
-  } satisfies RateLimitConfig,
-  tokenCache: { ttlMs: 0 },
-  modelNames: { client: 'HostOAuthClient', grant: 'HostOAuthGrant' } satisfies ModelNames,
-  collectionPrefix: 'oauth_',
-  audit: { retentionDays: 400 },
-  cors: { tokenEndpoint: false, origins: [] },
-  clockSkewMs: 5_000,
-  clientIdMetadata: {
-    enabled: true,
-    allowedHosts: ['claude.ai', '.chatgpt.com'],
-    cacheTtlMs: 3_600_000,
-    fetchTimeoutMs: 5_000,
-    maxBytes: 65_536,
-    allowedScopes: ['contacts.read'],
-  } satisfies ClientIdMetadataConfig,
-};
-
-// `allowedHosts` is required whenever the key is present at all — the type is
-// what stops "enabled, with no allowlist" from compiling in the first place.
-const cimdMinimal: ClientIdMetadataConfig = { allowedHosts: ['claude.ai'] };
-
-// A resource may narrow the catalog.
-const narrowed: ResourceSpec = {
-  id: 'https://api.example.com/mcp',
-  label: 'MCP',
-  scopes: ['contacts.read'],
-};
-const scopeSpec: ScopeSpec = { id: 'a', label: 'A', description: 'd', sensitive: true, oidc: false };
-
-// ---------------------------------------------------------------------------
-// The instance surface — §2's one screen, checked from outside.
-// ---------------------------------------------------------------------------
-const routers: OAuthHostRouters = oauth.routes;
-void routers.discovery;
-void routers.oauth;
-
-// Both call shapes the docs show.
-void oauth.protect('contacts.read');
-void oauth.protect(['a', 'b'], { mode: 'any', resource: 'https://api.example.com/mcp' } satisfies ProtectOptions);
-void oauth.protect();
-
-declare const spec: CreateClientSpec;
-async function adminSurface(): Promise<void> {
-  const clients: ClientsApi = oauth.clients;
-  const created: CreatedClient = await clients.create(spec);
-  // The secret is a plain string, returned once. If this ever becomes optional
-  // the provisioning script silently stops printing it.
-  const secret: string = created.clientSecret;
-  void secret;
-  await clients.rotateSecret(created.clientId, { retireAfter: 86_400_000, label: 'q3' });
-  await clients.update(created.clientId, { name: 'Claude', redirectUris: [] });
-  await clients.get(created.clientId);
-  await clients.list({ status: 'active', limit: 10, skip: 0 });
-  await clients.disable(created.clientId);
-
-  const grants: GrantsApi = oauth.grants;
-  const listed = await grants.list({ userId: 'u1', limit: 10 });
-  const summary: GrantSummary = listed.items[0]!;
-  void summary.client.branding;
-  await grants.revoke(summary.id, { by: 'user' });
-
-  const users: UsersApi = oauth.users;
-  await users.forget('u1');
-  await users.revokeAll('u1', { reason: 'password_change' });
-
-  const contexts: ContextsApi = oauth.contexts;
-  await contexts.revoked('u1', 'org_1');
-
-  await oauth.syncIndexes();
-  const models: OAuthModels = oauth.models;
-  void models.Client;
-  void models.Grant;
-  void models.Code;
-  void models.Token;
-  void models.Request;
-  void models.Key;
-  void models.Audit;
-}
-
-// ---------------------------------------------------------------------------
-// Documents, as a host would type its own queries against them.
-// ---------------------------------------------------------------------------
-declare const client: OAuthClientDoc;
-declare const grant: OAuthGrantDoc;
-declare const code: OAuthCodeDoc;
-declare const token: OAuthTokenDoc;
-declare const request: OAuthRequestDoc;
-declare const key: OAuthKeyDoc;
-declare const audit: OAuthAuditDoc;
-declare const publicClient: PublicClient;
-declare const branding: ClientBranding;
-declare const secretRecord: ClientSecretRecord;
-declare const user: PackageUser;
-declare const userId: UserId;
-declare const resolve: ResolveUser;
-declare const err: OAuthError;
-
-void client.secrets;
-void grant.contextId;
-void code.codeChallengeMethod;
-// The rotation chain has to be reachable from outside, or reuse detection is
-// unverifiable by anyone auditing this package.
-void token.familyId;
-void token.parentId;
-void request.requestId;
-void key.publicJwk;
-void audit.type;
-void publicClient.clientId;
-// A CIMD row must be distinguishable from a hand-registered one from outside —
-// a "connected apps" screen showing both has to be able to say which is which.
-void publicClient.registration;
-void publicClient.metadataUrl;
-void client.registration;
-void client.metadataUrl;
-void client.metadataFetchedAt;
-void client.metadataEtag;
-void branding.logoUrl;
-void secretRecord.retiresAt;
-void user.authTime;
-void userId;
-void resolve;
-void err.code;
-
-// The contract `mcp-server` consumes — plan §6 fixes it here.
-declare const reqCtx: OAuthRequestContext;
-void reqCtx.userId;
-void reqCtx.clientId;
-void reqCtx.contextId;
-void reqCtx.scopes;
-void reqCtx.grantId;
-void reqCtx.tokenId;
-void reqCtx.audience;
-
-void minimal;
-void shorthandScopes;
-void withDefaultScopes;
-void withFn;
-void withAdapter;
-void withLoad;
-void bothOnAdapter;
-void anon;
-void asyncUser;
-void tenanted;
-void tuned;
-void narrowed;
-void scopeSpec;
-void cimdMinimal;
-void adminSurface;