@willyim/idp 0.3.1 → 0.5.0

package/README.md

@@ -323,6 +323,55 @@ ingest token, say — identifies a site rather than a user, cannot be kept secre
 and must not pay a round trip per hit. Keep those in the app's own table and
 gate them on `Origin` plus rate limiting.
 
+## Linked identities
+
+A user's ids on *other* systems — their Slack member id, their WhatsApp number,
+a Telegram id — pinned to their IdP user. The point is that an app hearing from
+someone on Slack asks the IdP "who is this, and what may they do here?" and gets
+the same answer a browser session for that person would carry. The app keeps no
+table of Slack ids: the one it would write is exactly the allowlist the IdP
+exists to replace.
+
+Linking is **superadmin-only** — a link asserts identity with nothing to prove
+it, so no app and no member may do it:
+
+```sh
+curl -X POST https://idp.willy.im/api/v1/users/<userId>/identities \
+  -H "authorization: Bearer wim_<admin key>" -H "content-type: application/json" \
+  -d '{"provider":"slack","externalId":"U0AAE7LAATD","label":"house workspace"}'
+```
+
+Resolving is app-scoped and needs `identity:resolve` on the app's own key:
+
+```ts
+import { createIdentities, grants } from "@willyim/idp"
+
+const identities = createIdentities({
+  baseUrl: "https://idp.willy.im",
+  token: env.IDP_MANAGEMENT_KEY, // the app's wim_… key, with identity:resolve
+  app: "bender",
+})
+
+// On every inbound Slack message:
+const who = await identities.resolve("slack", event.user)
+if (!who.found) return                               // store it, do not answer
+if (!grants(who.permissions, "chat:respond")) return // they exist, this app never granted them
+who.userId // the IdP user — the same id a session or a wak_ key would carry
+```
+
+`permissions` are the user's product permissions for **the asking app**,
+computed by the same code the claims hook runs at token mint: an admin member
+gets the whole catalog, a plain member gets their grants, a linked user with no
+membership resolves as `found: true` with none. `found: false` is a miss, not an
+error, and is the common case in any shared channel.
+
+Verdicts are cached by `(provider, externalId)` — 60s for a hit and for a miss,
+both tunable via `cache` — and concurrent lookups of the same pair share one
+round trip. A failed round trip is never cached. The miss TTL bounds how fast a
+*new* link takes effect; call `forget(provider, externalId)` after one you made
+yourself. The provider is case-insensitive; the id is exact, as the other
+system spells it.
+
 ## Management API types
 
 Endpoints without sugar of their own go through `createManagementApi`, whose

package/dist/src/identities.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Linked identities, from the consuming app's side: "someone just messaged me
+ * on Slack as U0AAE7LAATD — who is that, and what may they do here?"
+ *
+ * The IdP is the only place the answer lives. A user's ids on other systems
+ * are pinned to their IdP user by a superadmin (the management API's
+ * `/users/{userId}/identities`), and an app resolves them with its own scoped
+ * `wim_…` key. The app never keeps a table of Slack ids — the one it would
+ * write is exactly the allowlist the IdP exists to replace.
+ *
+ * `permissions` in the answer are the user's product permissions for THIS app,
+ * computed the same way the claims hook computes them at token mint, so a
+ * Slack message and a browser session from the same person carry the same
+ * grants. Enforcement stays the app's job, same as everywhere else; `grants()`
+ * from `./claims.js` is the matcher to use.
+ *
+ * Resolution is a network round trip on a hot path — every inbound chat
+ * message — so verdicts are cached by (provider, externalId) with a short TTL,
+ * and concurrent lookups of the same pair share one request. A miss is cached
+ * too (most messages in any shared channel are from people who are not
+ * linked), which bounds how quickly a NEW link takes effect: `cache.missTtlMs`.
+ * A failed round trip is never cached, so an IdP blip does not lock anyone out
+ * for the whole TTL. `forget()` after a link you performed yourself.
+ */
+import type { z } from "zod";
+import { type ManagementApiOptions } from "./api.js";
+import type { IdentityResolutionSchema } from "./schemas/index.js";
+/** The IdP's answer. `found: false` is data, not an error. */
+export type IdentityResolution = z.output<typeof IdentityResolutionSchema>;
+/** The `found: true` half. */
+export type ResolvedIdentity = Extract<IdentityResolution, {
+    found: true;
+}>;
+export type IdentityCacheOptions = {
+    /** How long a `found: true` verdict is reused. Default 60s. */
+    ttlMs?: number;
+    /** How long a `found: false` verdict is reused. Default 60s — see the header. */
+    missTtlMs?: number;
+    /** Entry ceiling before the oldest are dropped. Default 1000. */
+    max?: number;
+};
+export type IdentitiesOptions = ManagementApiOptions & {
+    /** The app the permissions in each answer are scoped to. */
+    app: string;
+    /** `false` disables caching entirely (every resolve is a round trip). */
+    cache?: IdentityCacheOptions | false;
+    /** Clock seam, for tests. */
+    now?: () => number;
+};
+export declare function createIdentities(options: IdentitiesOptions): {
+    resolve: (provider: string, externalId: string, init?: {
+        signal?: AbortSignal;
+        fresh?: boolean;
+    }) => Promise<IdentityResolution>;
+    /** Drops one pair's cached verdict, or the whole cache when called bare. */
+    forget(provider?: string, externalId?: string): void;
+};
+export type Identities = ReturnType<typeof createIdentities>;
+//# sourceMappingURL=identities.d.ts.map

package/dist/src/identities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identities.d.ts","sourceRoot":"","sources":["../../src/identities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAE5B,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,UAAU,CAAA;AACzE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAA;AAElE,8DAA8D;AAC9D,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE1E,8BAA8B;AAC9B,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,EAAE;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,CAAC,CAAA;AAE3E,MAAM,MAAM,oBAAoB,GAAG;IACjC,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG,oBAAoB,GAAG;IACrD,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAA;IACX,yEAAyE;IACzE,KAAK,CAAC,EAAE,oBAAoB,GAAG,KAAK,CAAA;IACpC,6BAA6B;IAC7B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB,CAAA;AAQD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB;wBAiC7C,MAAM,cACJ,MAAM,SACZ;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAC9C,OAAO,CAAC,kBAAkB,CAAC;IAgC5B,4EAA4E;sBAC1D,MAAM,eAAe,MAAM,GAAG,IAAI;EAQvD;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAA"}

package/dist/src/index.d.ts

@@ -18,6 +18,8 @@ export { memorySessions, type MemorySessionStore, type SessionRecord, type Sessi
 export { grants, normalizeClaims, PERMISSIONS_CLAIM, WORKSPACES_CLAIM, type Actor, type Claims, type Workspace, } from "./claims.js";
 export { createManagementApi, type ManagementApi, type ManagementApiOptions, } from "./api.js";
 export { createUserKeys, readApiKey, type AuthenticatedKey, type AuthenticateOptions, type AuthenticateResult, type CreateUserApiKeyInput, type ListFilter, type MintedUserApiKey, type UserApiKey, type UserKeyCacheOptions, type UserKeys, type UserKeysOptions, type UserKeyValidation, } from "./user-keys.js";
+export { createIdentities, type Identities, type IdentitiesOptions, type IdentityCacheOptions, type ResolvedIdentity, type IdentityResolution, } from "./identities.js";
+export { createResourceServer, type ResourceServer, type ResourceServerOptions, type VerifiedAccessToken, type AuthResult, } from "./resource-server.js";
 export { parseDuration, type Duration } from "./duration.js";
 export { clearCookie, parseCookies, readCookie, serializeCookie, type CookieOptions, } from "./cookie.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,eAAe,EACf,UAAU,EACV,cAAc,EACd,QAAQ,EACR,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,QAAQ,EACb,KAAK,MAAM,GACZ,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,SAAS,EACT,sBAAsB,EACtB,QAAQ,EACR,KAAK,GAAG,EACR,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,cAAc,GACpB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,cAAc,EACd,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,MAAM,EACN,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,KAAK,EACV,KAAK,MAAM,EACX,KAAK,SAAS,GACf,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,mBAAmB,EACnB,KAAK,aAAa,EAClB,KAAK,oBAAoB,GAC1B,MAAM,UAAU,CAAA;AAEjB,OAAO,EACL,cAAc,EACd,UAAU,EACV,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC5D,OAAO,EACL,WAAW,EACX,YAAY,EACZ,UAAU,EACV,eAAe,EACf,KAAK,aAAa,GACnB,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,eAAe,EACf,UAAU,EACV,cAAc,EACd,QAAQ,EACR,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,QAAQ,EACb,KAAK,MAAM,GACZ,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,SAAS,EACT,sBAAsB,EACtB,QAAQ,EACR,KAAK,GAAG,EACR,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,cAAc,GACpB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,cAAc,EACd,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,MAAM,EACN,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,KAAK,EACV,KAAK,MAAM,EACX,KAAK,SAAS,GACf,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,mBAAmB,EACnB,KAAK,aAAa,EAClB,KAAK,oBAAoB,GAC1B,MAAM,UAAU,CAAA;AAEjB,OAAO,EACL,cAAc,EACd,UAAU,EACV,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EACL,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,iBAAiB,CAAA;AAExB,OAAO,EACL,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,UAAU,GAChB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC5D,OAAO,EACL,WAAW,EACX,YAAY,EACZ,UAAU,EACV,eAAe,EACf,KAAK,aAAa,GACnB,MAAM,aAAa,CAAA"}

package/dist/src/index.js

@@ -18,5 +18,7 @@ export { memorySessions, } from "./store.js";
 export { grants, normalizeClaims, PERMISSIONS_CLAIM, WORKSPACES_CLAIM, } from "./claims.js";
 export { createManagementApi, } from "./api.js";
 export { createUserKeys, readApiKey, } from "./user-keys.js";
+export { createIdentities, } from "./identities.js";
+export { createResourceServer, } from "./resource-server.js";
 export { parseDuration } from "./duration.js";
 export { clearCookie, parseCookies, readCookie, serializeCookie, } from "./cookie.js";

package/dist/src/resource-server.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Being an OAuth 2.1 resource server against the willy.im IdP — which is what
+ * an MCP server is.
+ *
+ * The MCP authorization spec is plain OAuth with three discovery hops, and
+ * every one of them is either served by the IdP already or is a static
+ * document this module writes for you:
+ *
+ *   1. The client hits the resource without a token and gets a 401 carrying
+ *      `WWW-Authenticate: Bearer resource_metadata="…"`   → `challenge()`
+ *   2. It fetches that URL, the Protected Resource Metadata (RFC 9728), which
+ *      names the authorization server                       → `metadata()`
+ *   3. It fetches the AS metadata (RFC 8414) from the IdP, registers itself
+ *      (RFC 7591), runs authorization code + PKCE with `resource=` (RFC 8707),
+ *      and comes back with a JWT access token whose `aud` is this resource.
+ *   4. The resource server verifies that JWT against the IdP's JWKS and reads
+ *      the permissions claim                                → `authenticate()`
+ *
+ * Step 4 is the only one with any real code, and it is deliberately small:
+ * signature (EdDSA/Ed25519, ES256 or RS256 via WebCrypto — no jose, no deps),
+ * issuer, audience, time. The permissions on the token were computed by the
+ * IdP for the app that owns this resource (the same way a browser session's
+ * are), so the app looks nothing up — it reads a claim and matches it with
+ * `grants()` like everywhere else.
+ *
+ * The JWKS is cached and refetched once on an unknown `kid`, which is how a key
+ * rotation at the IdP is picked up without a restart.
+ */
+export declare const PERMISSIONS_CLAIM = "https://willy.im/permissions";
+export declare const APP_CLAIM = "https://willy.im/app";
+export type ResourceServerOptions = {
+    /** The IdP's OAuth issuer — `https://idp.willy.im/auth` (note the /auth). */
+    issuer: string;
+    /**
+     * This server's canonical URI, exactly as registered on the application in
+     * the IdP (`resources`) — e.g. `https://bender.romo.fyi/mcp`. It is the
+     * audience a token must carry, compared byte for byte.
+     */
+    resource: string;
+    /** Defaults to `${issuer}/jwks`. */
+    jwksUrl?: string;
+    /** Advertised in the metadata document. Informational only. */
+    scopesSupported?: string[];
+    /** How long a fetched JWKS is reused. Default 10 minutes. */
+    jwksTtlMs?: number;
+    /** Clock skew tolerated on exp/nbf. Default 60s. */
+    leewaySeconds?: number;
+    fetch?: typeof fetch;
+    /** Clock seam, for tests. */
+    now?: () => number;
+};
+/** A verified access token, reduced to what an app acts on. */
+export type VerifiedAccessToken = {
+    /** The IdP user id — the same `sub` a session or a wak_ key resolves to. */
+    sub: string;
+    /** The app the permissions are for (the owner of `resource`), when present. */
+    app: string | null;
+    /** The user's product permissions for that app. Match with `has()`/`grants()`. */
+    permissions: string[];
+    /** Space-delimited OAuth scopes on the token (openid/profile/…), if any. */
+    scopes: string[];
+    /** Everything else on the token, for a caller that needs a raw claim. */
+    claims: Record<string, unknown>;
+};
+export type AuthResult = {
+    ok: true;
+    token: VerifiedAccessToken;
+} | {
+    ok: false;
+    status: 401 | 403;
+    error: string;
+    description: string;
+};
+export declare function createResourceServer(options: ResourceServerOptions): {
+    verify: (token: string) => Promise<AuthResult>;
+    authenticate: (request: {
+        headers: {
+            get(name: string): string | null;
+        };
+    }, init?: {
+        permissions?: string[];
+    }) => Promise<AuthResult>;
+    challenge: (error?: {
+        error: string;
+        description: string;
+    }) => string;
+    metadata: () => Record<string, unknown>;
+};
+export type ResourceServer = ReturnType<typeof createResourceServer>;
+//# sourceMappingURL=resource-server.d.ts.map

package/dist/src/resource-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-server.d.ts","sourceRoot":"","sources":["../../src/resource-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,eAAO,MAAM,iBAAiB,iCAAiC,CAAA;AAC/D,eAAO,MAAM,SAAS,yBAAyB,CAAA;AAE/C,MAAM,MAAM,qBAAqB,GAAG;IAClC,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;IAC1B,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oDAAoD;IACpD,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB,6BAA6B;IAC7B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB,CAAA;AAED,+DAA+D;AAC/D,MAAM,MAAM,mBAAmB,GAAG;IAChC,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAA;IACX,+EAA+E;IAC/E,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,kFAAkF;IAClF,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,4EAA4E;IAC5E,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAChC,CAAA;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,GACxC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAA;AAgDxE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB;oBAiDpC,MAAM,KAAG,OAAO,CAAC,UAAU,CAAC;4BA8D9C;QAAE,OAAO,EAAE;YAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;SAAE,CAAA;KAAE,SACpD;QAAE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,KAC/B,OAAO,CAAC,UAAU,CAAC;wBAwBK;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,KAAG,MAAM;oBAarD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;EAU7C;AAED,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAA"}

package/dist/src/resource-server.js

@@ -0,0 +1,206 @@
+/**
+ * Being an OAuth 2.1 resource server against the willy.im IdP — which is what
+ * an MCP server is.
+ *
+ * The MCP authorization spec is plain OAuth with three discovery hops, and
+ * every one of them is either served by the IdP already or is a static
+ * document this module writes for you:
+ *
+ *   1. The client hits the resource without a token and gets a 401 carrying
+ *      `WWW-Authenticate: Bearer resource_metadata="…"`   → `challenge()`
+ *   2. It fetches that URL, the Protected Resource Metadata (RFC 9728), which
+ *      names the authorization server                       → `metadata()`
+ *   3. It fetches the AS metadata (RFC 8414) from the IdP, registers itself
+ *      (RFC 7591), runs authorization code + PKCE with `resource=` (RFC 8707),
+ *      and comes back with a JWT access token whose `aud` is this resource.
+ *   4. The resource server verifies that JWT against the IdP's JWKS and reads
+ *      the permissions claim                                → `authenticate()`
+ *
+ * Step 4 is the only one with any real code, and it is deliberately small:
+ * signature (EdDSA/Ed25519, ES256 or RS256 via WebCrypto — no jose, no deps),
+ * issuer, audience, time. The permissions on the token were computed by the
+ * IdP for the app that owns this resource (the same way a browser session's
+ * are), so the app looks nothing up — it reads a claim and matches it with
+ * `grants()` like everywhere else.
+ *
+ * The JWKS is cached and refetched once on an unknown `kid`, which is how a key
+ * rotation at the IdP is picked up without a restart.
+ */
+import { grants } from "./claims.js";
+export const PERMISSIONS_CLAIM = "https://willy.im/permissions";
+export const APP_CLAIM = "https://willy.im/app";
+const DEFAULT_JWKS_TTL_MS = 600_000;
+const DEFAULT_LEEWAY_S = 60;
+function b64urlToBytes(s) {
+    const pad = s.length % 4 === 0 ? "" : "=".repeat(4 - (s.length % 4));
+    const b = atob(s.replace(/-/g, "+").replace(/_/g, "/") + pad);
+    const out = new Uint8Array(b.length);
+    for (let i = 0; i < b.length; i++)
+        out[i] = b.charCodeAt(i);
+    return out;
+}
+function decodeJson(segment) {
+    return JSON.parse(new TextDecoder().decode(b64urlToBytes(segment)));
+}
+/** The WebCrypto import + verify params for the algorithms the IdP may sign with. */
+function algParams(alg, jwk) {
+    switch (alg) {
+        case "EdDSA":
+            return { importAlg: { name: "Ed25519" }, verifyAlg: { name: "Ed25519" } };
+        case "ES256":
+            return { importAlg: { name: "ECDSA", namedCurve: "P-256" }, verifyAlg: { name: "ECDSA", hash: "SHA-256" } };
+        case "RS256":
+            return {
+                importAlg: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+                verifyAlg: { name: "RSASSA-PKCS1-v1_5" },
+            };
+        default:
+            return jwk.kty ? null : null;
+    }
+}
+export function createResourceServer(options) {
+    const doFetch = options.fetch ?? fetch;
+    const now = options.now ?? (() => Date.now());
+    const jwksUrl = options.jwksUrl ?? `${options.issuer.replace(/\/$/, "")}/jwks`;
+    const jwksTtlMs = options.jwksTtlMs ?? DEFAULT_JWKS_TTL_MS;
+    const leeway = (options.leewaySeconds ?? DEFAULT_LEEWAY_S) * 1000;
+    let jwks = null;
+    async function loadJwks(force) {
+        if (!force && jwks && now() - jwks.at < jwksTtlMs)
+            return jwks.keys;
+        const res = await doFetch(jwksUrl);
+        if (!res.ok)
+            throw new Error(`jwks fetch failed: ${res.status}`);
+        const body = (await res.json());
+        jwks = { at: now(), keys: body.keys ?? [] };
+        return jwks.keys;
+    }
+    /** Find the signing key by kid, refetching ONCE on a miss to catch rotation. */
+    async function keyFor(kid) {
+        const pick = (keys) => keys.find((k) => (kid ? k.kid === kid : true)) ?? null;
+        let key = pick(await loadJwks(false));
+        if (!key)
+            key = pick(await loadJwks(true));
+        return key;
+    }
+    async function verifySignature(header, signingInput, signature) {
+        const jwk = await keyFor(header.kid);
+        if (!jwk)
+            return false;
+        const params = algParams(header.alg, jwk);
+        if (!params)
+            return false;
+        const key = await crypto.subtle.importKey("jwk", jwk, params.importAlg, false, ["verify"]);
+        return crypto.subtle.verify(params.verifyAlg, key, signature, new TextEncoder().encode(signingInput));
+    }
+    /**
+     * Verifies a raw bearer token. Returns a discriminated result rather than
+     * throwing, so the caller owns the response shape. `insufficient_scope` is a
+     * 403; everything about the token being absent or bad is a 401.
+     */
+    async function verify(token) {
+        const parts = token.split(".");
+        if (parts.length !== 3) {
+            return { ok: false, status: 401, error: "invalid_token", description: "Not a JWT." };
+        }
+        let header;
+        let claims;
+        try {
+            header = decodeJson(parts[0]);
+            claims = decodeJson(parts[1]);
+        }
+        catch {
+            return { ok: false, status: 401, error: "invalid_token", description: "Malformed JWT." };
+        }
+        let valid = false;
+        try {
+            valid = await verifySignature(header, `${parts[0]}.${parts[1]}`, b64urlToBytes(parts[2]));
+        }
+        catch {
+            valid = false;
+        }
+        if (!valid) {
+            return { ok: false, status: 401, error: "invalid_token", description: "Bad signature." };
+        }
+        if (claims.iss !== options.issuer) {
+            return { ok: false, status: 401, error: "invalid_token", description: "Wrong issuer." };
+        }
+        const aud = claims.aud;
+        const audOk = Array.isArray(aud) ? aud.includes(options.resource) : aud === options.resource;
+        if (!audOk) {
+            return { ok: false, status: 401, error: "invalid_token", description: "Token is for a different resource." };
+        }
+        const t = now();
+        if (typeof claims.exp === "number" && t > claims.exp * 1000 + leeway) {
+            return { ok: false, status: 401, error: "invalid_token", description: "Token expired." };
+        }
+        if (typeof claims.nbf === "number" && t < claims.nbf * 1000 - leeway) {
+            return { ok: false, status: 401, error: "invalid_token", description: "Token not yet valid." };
+        }
+        const permissions = Array.isArray(claims[PERMISSIONS_CLAIM])
+            ? claims[PERMISSIONS_CLAIM].filter((p) => typeof p === "string")
+            : [];
+        const scopes = typeof claims.scope === "string" ? claims.scope.split(" ").filter(Boolean) : [];
+        return {
+            ok: true,
+            token: {
+                sub: String(claims.sub ?? ""),
+                app: typeof claims[APP_CLAIM] === "string" ? claims[APP_CLAIM] : null,
+                permissions,
+                scopes,
+                claims,
+            },
+        };
+    }
+    /**
+     * The whole check off a `Request`: pull the bearer, verify it, and confirm
+     * every required permission (wildcard-aware via `grants()`). Returns a
+     * result rather than throwing.
+     */
+    async function authenticate(request, init = {}) {
+        const authz = request.headers.get("authorization");
+        const bearer = authz && /^Bearer\s+(.+)$/i.exec(authz.trim())?.[1];
+        if (!bearer) {
+            return { ok: false, status: 401, error: "invalid_token", description: "No bearer token." };
+        }
+        const verified = await verify(bearer.trim());
+        if (!verified.ok)
+            return verified;
+        const missing = (init.permissions ?? []).filter((p) => !grants(verified.token.permissions, p));
+        if (missing.length) {
+            return {
+                ok: false,
+                status: 403,
+                error: "insufficient_scope",
+                description: `Missing permission(s): ${missing.join(", ")}.`,
+            };
+        }
+        return verified;
+    }
+    /**
+     * The `WWW-Authenticate` value for a 401, pointing a client at the metadata
+     * document so it can discover how to get a token (RFC 9728 §5.1).
+     */
+    function challenge(error) {
+        const parts = [
+            `Bearer resource_metadata="${options.resource}/.well-known/oauth-protected-resource"`,
+        ];
+        if (error)
+            parts.push(`error="${error.error}"`, `error_description="${error.description}"`);
+        return parts.join(", ");
+    }
+    /**
+     * The Protected Resource Metadata document (RFC 9728) — served at
+     * `/.well-known/oauth-protected-resource`. It names this resource and the
+     * IdP as its authorization server; the client takes it from there.
+     */
+    function metadata() {
+        return {
+            resource: options.resource,
+            authorization_servers: [options.issuer],
+            bearer_methods_supported: ["header"],
+            ...(options.scopesSupported ? { scopes_supported: options.scopesSupported } : {}),
+        };
+    }
+    return { verify, authenticate, challenge, metadata };
+}

package/dist/src/schemas/index.d.ts

@@ -16,6 +16,7 @@ export declare const ApplicationSchema: z.ZodObject<{
     app: z.ZodNullable<z.ZodString>;
     allowSignup: z.ZodBoolean;
     permissions: z.ZodArray<z.ZodString>;
+    resources: z.ZodArray<z.ZodString>;
     redirectUris: z.ZodArray<z.ZodString>;
     disabled: z.ZodBoolean;
     createdAt: z.ZodString;
@@ -41,6 +42,7 @@ export declare const ApplicationListSchema: z.ZodObject<{
         app: z.ZodNullable<z.ZodString>;
         allowSignup: z.ZodBoolean;
         permissions: z.ZodArray<z.ZodString>;
+        resources: z.ZodArray<z.ZodString>;
         redirectUris: z.ZodArray<z.ZodString>;
         disabled: z.ZodBoolean;
         createdAt: z.ZodString;
@@ -66,6 +68,7 @@ export declare const UpdateApplicationInput: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
     redirectUris: z.ZodOptional<z.ZodArray<z.ZodString>>;
     allowSignup: z.ZodOptional<z.ZodBoolean>;
+    resources: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export declare const ClientSecretSchema: z.ZodObject<{
     clientSecret: z.ZodString;
@@ -219,6 +222,42 @@ export declare const UserApiKeyValidationSchema: z.ZodUnion<readonly [z.ZodObjec
         not_found: "not_found";
     }>;
 }, z.core.$strip>]>;
+export declare const LinkedIdentitySchema: z.ZodObject<{
+    id: z.ZodString;
+    userId: z.ZodString;
+    provider: z.ZodString;
+    externalId: z.ZodString;
+    label: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export declare const LinkedIdentityListSchema: z.ZodObject<{
+    identities: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        userId: z.ZodString;
+        provider: z.ZodString;
+        externalId: z.ZodString;
+        label: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const LinkIdentityInput: z.ZodObject<{
+    provider: z.ZodString;
+    externalId: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const LinkedIdentityCreatedSchema: z.ZodObject<{
+    id: z.ZodString;
+    created: z.ZodBoolean;
+}, z.core.$strip>;
+export declare const IdentityResolutionSchema: z.ZodUnion<readonly [z.ZodObject<{
+    found: z.ZodLiteral<true>;
+    userId: z.ZodString;
+    email: z.ZodString;
+    name: z.ZodNullable<z.ZodString>;
+    permissions: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    found: z.ZodLiteral<false>;
+}, z.core.$strip>]>;
 export declare const AuditEntrySchema: z.ZodObject<{
     id: z.ZodNumber;
     tableName: z.ZodString;

package/dist/src/schemas/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/schemas/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,eAAO,MAAM,iBAAiB;;;;;;;;;iBAS5B,CAAA;AAEF,eAAO,MAAM,UAAU;;;;;;iBAMrB,CAAA;AAEF,eAAO,MAAM,eAAe;;;;;;iBAM1B,CAAA;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;iBAAyD,CAAA;AAE3F;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;;;;iBAejC,CAAA;AACF,eAAO,MAAM,wBAAwB;;;;iBAInC,CAAA;AAEF,uEAAuE;AACvE,eAAO,MAAM,sBAAsB;;;;iBAIjC,CAAA;AAEF,eAAO,MAAM,kBAAkB;;iBAE7B,CAAA;AAEF,+DAA+D;AAC/D,eAAO,MAAM,sBAAsB;;iBAEjC,CAAA;AACF,eAAO,MAAM,oBAAoB;;iBAAiD,CAAA;AAClF,eAAO,MAAM,cAAc;;;;;;;;iBAA2C,CAAA;AACtE,eAAO,MAAM,mBAAmB;;;;;;;;iBAAqD,CAAA;AAIrF,eAAO,MAAM,UAAU;;;EAA8B,CAAA;AAErD,eAAO,MAAM,YAAY;;;;;;;;;iBAMvB,CAAA;AACF,eAAO,MAAM,gBAAgB;;;;;;;;;;;iBAA+C,CAAA;AAE5E,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB;;;;;;;iBAI5B,CAAA;AACF,eAAO,MAAM,kBAAkB;;;;;iBAG7B,CAAA;AAEF,eAAO,MAAM,iBAAiB;;;;;;iBAG5B,CAAA;AAEF,eAAO,MAAM,oBAAoB;;;iBAM/B,CAAA;AACF,eAAO,MAAM,sBAAsB;;;;iBAIjC,CAAA;AAEF,eAAO,MAAM,QAAQ;;iBAAoC,CAAA;AAIzD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;iBAW3B,CAAA;AACF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;iBAAgD,CAAA;AAEjF,eAAO,MAAM,qBAAqB;;;;;;iBAMhC,CAAA;AACF,eAAO,MAAM,uBAAuB;;;;iBAIlC,CAAA;AAEF,eAAO,MAAM,uBAAuB;;iBAAyC,CAAA;AAC7E,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;mBAUrC,CAAA;AAEF,eAAO,MAAM,gBAAgB;;;;;;;;iBAQ3B,CAAA;AACF,eAAO,MAAM,eAAe;;;;;;;;;;iBAAmD,CAAA;AAI/E,eAAO,MAAM,YAAY;;;;;;;;;;;;;;iBAUvB,CAAA;AACF,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;iBAA4C,CAAA;AAEzE,eAAO,MAAM,iBAAiB;;;;iBAM5B,CAAA;AACF,eAAO,MAAM,mBAAmB;;;;iBAI9B,CAAA;AAIF,eAAO,MAAM,cAAc;;;;;;;;;;;;;iBASzB,CAAA;AACF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;iBAA8C,CAAA;AAE7E,eAAO,MAAM,mBAAmB;;;iBAG9B,CAAA;AACF,eAAO,MAAM,qBAAqB;;;;iBAIhC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/schemas/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,eAAO,MAAM,iBAAiB;;;;;;;;;;iBAY5B,CAAA;AAEF,eAAO,MAAM,UAAU;;;;;;iBAMrB,CAAA;AAEF,eAAO,MAAM,eAAe;;;;;;iBAM1B,CAAA;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;iBAAyD,CAAA;AAE3F;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;;;;iBAejC,CAAA;AACF,eAAO,MAAM,wBAAwB;;;;iBAInC,CAAA;AAEF,uEAAuE;AACvE,eAAO,MAAM,sBAAsB;;;;;iBAQjC,CAAA;AAEF,eAAO,MAAM,kBAAkB;;iBAE7B,CAAA;AAEF,+DAA+D;AAC/D,eAAO,MAAM,sBAAsB;;iBAEjC,CAAA;AACF,eAAO,MAAM,oBAAoB;;iBAAiD,CAAA;AAClF,eAAO,MAAM,cAAc;;;;;;;;iBAA2C,CAAA;AACtE,eAAO,MAAM,mBAAmB;;;;;;;;iBAAqD,CAAA;AAIrF,eAAO,MAAM,UAAU;;;EAA8B,CAAA;AAErD,eAAO,MAAM,YAAY;;;;;;;;;iBAMvB,CAAA;AACF,eAAO,MAAM,gBAAgB;;;;;;;;;;;iBAA+C,CAAA;AAE5E,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB;;;;;;;iBAI5B,CAAA;AACF,eAAO,MAAM,kBAAkB;;;;;iBAG7B,CAAA;AAEF,eAAO,MAAM,iBAAiB;;;;;;iBAG5B,CAAA;AAEF,eAAO,MAAM,oBAAoB;;;iBAM/B,CAAA;AACF,eAAO,MAAM,sBAAsB;;;;iBAIjC,CAAA;AAEF,eAAO,MAAM,QAAQ;;iBAAoC,CAAA;AAIzD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;iBAW3B,CAAA;AACF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;iBAAgD,CAAA;AAEjF,eAAO,MAAM,qBAAqB;;;;;;iBAMhC,CAAA;AACF,eAAO,MAAM,uBAAuB;;;;iBAIlC,CAAA;AAEF,eAAO,MAAM,uBAAuB;;iBAAyC,CAAA;AAC7E,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;mBAUrC,CAAA;AAIF,eAAO,MAAM,oBAAoB;;;;;;;iBAO/B,CAAA;AACF,eAAO,MAAM,wBAAwB;;;;;;;;;iBAA0D,CAAA;AAE/F,eAAO,MAAM,iBAAiB;;;;iBAI5B,CAAA;AACF,eAAO,MAAM,2BAA2B;;;iBAGtC,CAAA;AAEF,eAAO,MAAM,wBAAwB;;;;;;;;mBAWnC,CAAA;AAEF,eAAO,MAAM,gBAAgB;;;;;;;;iBAQ3B,CAAA;AACF,eAAO,MAAM,eAAe;;;;;;;;;;iBAAmD,CAAA;AAI/E,eAAO,MAAM,YAAY;;;;;;;;;;;;;;iBAUvB,CAAA;AACF,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;iBAA4C,CAAA;AAEzE,eAAO,MAAM,iBAAiB;;;;iBAM5B,CAAA;AACF,eAAO,MAAM,mBAAmB;;;;iBAI9B,CAAA;AAIF,eAAO,MAAM,cAAc;;;;;;;;;;;;;iBASzB,CAAA;AACF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;iBAA8C,CAAA;AAE7E,eAAO,MAAM,mBAAmB;;;iBAG9B,CAAA;AACF,eAAO,MAAM,qBAAqB;;;;iBAIhC,CAAA"}

package/dist/src/schemas/index.js

@@ -16,6 +16,9 @@ export const ApplicationSchema = z.object({
     app: z.string().nullable().describe("Application key; consumer workspace claims are filtered by this"),
     allowSignup: z.boolean().describe("Whether unknown users may sign themselves up"),
     permissions: z.array(z.string()).describe("The app's declared product-permission catalog"),
+    resources: z
+        .array(z.string())
+        .describe("Protected resource URIs (e.g. the app's MCP server) — valid `resource` audiences for access tokens"),
     redirectUris: z.array(z.string()),
     disabled: z.boolean(),
     createdAt: z.string().describe("ISO 8601 timestamp"),
@@ -63,6 +66,10 @@ export const UpdateApplicationInput = z.object({
     name: z.string().min(1).optional(),
     redirectUris: z.array(z.string().min(1)).min(1).optional(),
     allowSignup: z.boolean().optional(),
+    resources: z
+        .array(z.string().url())
+        .optional()
+        .describe("Replace the app's protected resource URIs — absolute https, no fragment"),
 });
 export const ClientSecretSchema = z.object({
     clientSecret: z.string().describe("Plaintext client secret — shown exactly once, never stored"),
@@ -149,6 +156,37 @@ export const UserApiKeyValidationSchema = z.union([
     }),
     z.object({ valid: z.literal(false), reason: z.enum(["not_found", "revoked", "expired"]) }),
 ]);
+// --- Linked identities (a user's ids on other systems) ---
+export const LinkedIdentitySchema = z.object({
+    id: z.string(),
+    userId: z.string(),
+    provider: z.string().describe("The other system, lowercase — slack, whatsapp, telegram"),
+    externalId: z.string().describe("The id exactly as that system spells it"),
+    label: z.string().nullable(),
+    createdAt: z.string(),
+});
+export const LinkedIdentityListSchema = z.object({ identities: z.array(LinkedIdentitySchema) });
+export const LinkIdentityInput = z.object({
+    provider: z.string().min(1).describe("slack, whatsapp, telegram… — normalised to lowercase"),
+    externalId: z.string().min(1).describe("The id as that system spells it, e.g. a Slack member id"),
+    label: z.string().optional().describe("A human label for the console"),
+});
+export const LinkedIdentityCreatedSchema = z.object({
+    id: z.string(),
+    created: z.boolean().describe("false when the same pair was already this user's"),
+});
+export const IdentityResolutionSchema = z.union([
+    z.object({
+        found: z.literal(true),
+        userId: z.string(),
+        email: z.string(),
+        name: z.string().nullable(),
+        permissions: z
+            .array(z.string())
+            .describe("The user's product permissions for the asking app; admins get the whole catalog"),
+    }),
+    z.object({ found: z.literal(false) }),
+]);
 export const AuditEntrySchema = z.object({
     id: z.number(),
     tableName: z.string(),

package/dist/src/schemas/operations.d.ts

@@ -43,6 +43,7 @@ export declare const operations: {
                 app: z.ZodNullable<z.ZodString>;
                 allowSignup: z.ZodBoolean;
                 permissions: z.ZodArray<z.ZodString>;
+                resources: z.ZodArray<z.ZodString>;
                 redirectUris: z.ZodArray<z.ZodString>;
                 disabled: z.ZodBoolean;
                 createdAt: z.ZodString;
@@ -79,6 +80,7 @@ export declare const operations: {
             app: z.ZodNullable<z.ZodString>;
             allowSignup: z.ZodBoolean;
             permissions: z.ZodArray<z.ZodString>;
+            resources: z.ZodArray<z.ZodString>;
             redirectUris: z.ZodArray<z.ZodString>;
             disabled: z.ZodBoolean;
             createdAt: z.ZodString;
@@ -95,6 +97,7 @@ export declare const operations: {
             name: z.ZodOptional<z.ZodString>;
             redirectUris: z.ZodOptional<z.ZodArray<z.ZodString>>;
             allowSignup: z.ZodOptional<z.ZodBoolean>;
+            resources: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>;
         readonly successCode: "200";
         readonly success: z.ZodObject<{
@@ -103,6 +106,7 @@ export declare const operations: {
             app: z.ZodNullable<z.ZodString>;
             allowSignup: z.ZodBoolean;
             permissions: z.ZodArray<z.ZodString>;
+            resources: z.ZodArray<z.ZodString>;
             redirectUris: z.ZodArray<z.ZodString>;
             disabled: z.ZodBoolean;
             createdAt: z.ZodString;
@@ -471,6 +475,73 @@ export declare const operations: {
             ok: z.ZodLiteral<true>;
         }, z.core.$strip>;
     };
+    readonly "get /api/v1/users/{userId}/identities": {
+        readonly summary: "List a user's linked identities (their ids on other systems)";
+        readonly description: "Requires an admin key. Identities are global to the user, not per app — a Slack id identifies a person regardless of who is asking.";
+        readonly params: {
+            readonly userId: "IdP user id.";
+        };
+        readonly successCode: "200";
+        readonly success: z.ZodObject<{
+            identities: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                userId: z.ZodString;
+                provider: z.ZodString;
+                externalId: z.ZodString;
+                label: z.ZodNullable<z.ZodString>;
+                createdAt: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    };
+    readonly "post /api/v1/users/{userId}/identities": {
+        readonly summary: "Link an external id to a user";
+        readonly description: "Requires an admin key: a link asserts identity with nothing to prove it, so no app or member may do it. 201 on a new link, 200 when the same pair was already this user's, 409 `already_linked` when it belongs to someone else — an identity is never silently re-pointed.";
+        readonly params: {
+            readonly userId: "IdP user id.";
+        };
+        readonly input: z.ZodObject<{
+            provider: z.ZodString;
+            externalId: z.ZodString;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        readonly successCode: "201";
+        readonly success: z.ZodObject<{
+            id: z.ZodString;
+            created: z.ZodBoolean;
+        }, z.core.$strip>;
+    };
+    readonly "delete /api/v1/users/{userId}/identities/{id}": {
+        readonly summary: "Unlink an external id (idempotent)";
+        readonly description: "Requires an admin key.";
+        readonly params: {
+            readonly userId: "IdP user id.";
+            readonly id: "Linked identity id.";
+        };
+        readonly successCode: "200";
+        readonly success: z.ZodObject<{
+            ok: z.ZodLiteral<true>;
+        }, z.core.$strip>;
+    };
+    readonly "get /api/v1/apps/{app}/identities/{provider}/{externalId}": {
+        readonly summary: "Resolve an external id to a user and their permissions in this app";
+        readonly description: "The hot path for an app that hears from someone on another system. Always 200 with a `found` discriminator — a miss is data, and the common case in any shared channel. `permissions` are the user's product permissions for THIS app, computed exactly as the claims hook computes them at token mint, so a Slack message and a browser session from the same person carry the same grants. A user with no membership resolves as found with no permissions.";
+        readonly permission: "identity:resolve";
+        readonly params: {
+            readonly provider: "The other system, e.g. slack.";
+            readonly externalId: "The id as that system spells it.";
+            readonly app: "Application key (oauth_client.metadata.app).";
+        };
+        readonly successCode: "200";
+        readonly success: z.ZodUnion<readonly [z.ZodObject<{
+            found: z.ZodLiteral<true>;
+            userId: z.ZodString;
+            email: z.ZodString;
+            name: z.ZodNullable<z.ZodString>;
+            permissions: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            found: z.ZodLiteral<false>;
+        }, z.core.$strip>]>;
+    };
     readonly "get /api/v1/apps/{app}/audit": {
         readonly summary: "List recent audit entries";
         readonly permission: "audit:read";

package/dist/src/schemas/operations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../../src/schemas/operations.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAkCvB,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAA;AAEpE,iFAAiF;AACjF,MAAM,MAAM,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,CAAA;AAEnF,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,SAAS,UAAU,EAAE,CAAA;IAC7B,wEAAwE;IACxE,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACzC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,CAAC,CAAC,OAAO,CAAA;IACjB,WAAW,EAAE,KAAK,GAAG,KAAK,CAAA;IAC1B,OAAO,EAAE,CAAC,CAAC,OAAO,CAAA;CACnB,CAAA;AAKD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6M0B,CAAA;AAEjD,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAA;AAC1C,MAAM,MAAM,YAAY,GAAG,MAAM,UAAU,CAAA;AAE3C,mEAAmE;AACnE,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,UAAU,IAAI,YAAY,SAAS,MAAM,CAAC,GACrE,CAAC,SAAS,GAAG,CAAC,IAAI,MAAM,CAAC,EAAE,GACzB,CAAC,GACD,KAAK,GACP,KAAK,CAAA;AAET,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,EAAE,SAAS,YAAY,GAC/F,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,GACvB,KAAK,CAAA;AAET,iFAAiF;AACjF,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,GAAG,MAAM,IAAI,MAAM,IAAI,IAAI,MAAM,IAAI,EAAE,GAC5F,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,GAC3B,KAAK,CAAA;AAET,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAE7E"}
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../../src/schemas/operations.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAsCvB,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAA;AAEpE,iFAAiF;AACjF,MAAM,MAAM,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,CAAA;AAEnF,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,SAAS,UAAU,EAAE,CAAA;IAC7B,wEAAwE;IACxE,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACzC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,CAAC,CAAC,OAAO,CAAA;IACjB,WAAW,EAAE,KAAK,GAAG,KAAK,CAAA;IAC1B,OAAO,EAAE,CAAC,CAAC,OAAO,CAAA;CACnB,CAAA;AAKD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+O0B,CAAA;AAEjD,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAA;AAC1C,MAAM,MAAM,YAAY,GAAG,MAAM,UAAU,CAAA;AAE3C,mEAAmE;AACnE,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,UAAU,IAAI,YAAY,SAAS,MAAM,CAAC,GACrE,CAAC,SAAS,GAAG,CAAC,IAAI,MAAM,CAAC,EAAE,GACzB,CAAC,GACD,KAAK,GACP,KAAK,CAAA;AAET,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,EAAE,SAAS,YAAY,GAC/F,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,GACvB,KAAK,CAAA;AAET,iFAAiF;AACjF,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,GAAG,MAAM,IAAI,MAAM,IAAI,IAAI,MAAM,IAAI,EAAE,GAC5F,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,GAC3B,KAAK,CAAA;AAET,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAE7E"}

package/dist/src/schemas/operations.js

@@ -8,7 +8,7 @@
  * needs to learn about it.
  */
 import { z } from "zod";
-import { AdminKeyCreatedSchema, AdminKeyListSchema, ApiKeyCreatedSchema, ApiKeyListSchema, ApplicationCreatedSchema, ApplicationListSchema, ApplicationSchema, AppPermissionsSchema, AuditListSchema, ClientSecretSchema, CreateAdminKeyInput, CreateApiKeyInput, CreateApplicationInput, CreateUserApiKeyInput, CreateWorkspaceInput, InviteMemberInput, InviteMemberResult, MemberListSchema, OkSchema, SetAppPermissionsInput, UpdateApplicationInput, UpdateMemberInput, UserApiKeyCreatedSchema, UserApiKeyListSchema, UserApiKeyValidationSchema, UserListSchema, ValidateUserApiKeyInput, WorkspaceCreatedSchema, WorkspaceListSchema, } from "./index.js";
+import { AdminKeyCreatedSchema, AdminKeyListSchema, ApiKeyCreatedSchema, ApiKeyListSchema, ApplicationCreatedSchema, ApplicationListSchema, ApplicationSchema, AppPermissionsSchema, AuditListSchema, ClientSecretSchema, CreateAdminKeyInput, CreateApiKeyInput, CreateApplicationInput, CreateUserApiKeyInput, CreateWorkspaceInput, InviteMemberInput, InviteMemberResult, MemberListSchema, OkSchema, SetAppPermissionsInput, UpdateApplicationInput, UpdateMemberInput, UserApiKeyCreatedSchema, UserApiKeyListSchema, UserApiKeyValidationSchema, LinkedIdentityListSchema, LinkIdentityInput, LinkedIdentityCreatedSchema, IdentityResolutionSchema, UserListSchema, ValidateUserApiKeyInput, WorkspaceCreatedSchema, WorkspaceListSchema, } from "./index.js";
 const APP_PARAM = { app: "Application key (oauth_client.metadata.app)." };
 const CLIENT_PARAM = { clientId: "OAuth client id of the application." };
 export const operations = {
@@ -200,6 +200,36 @@ export const operations = {
         successCode: "200",
         success: OkSchema,
     },
+    "get /api/v1/users/{userId}/identities": {
+        summary: "List a user's linked identities (their ids on other systems)",
+        description: "Requires an admin key. Identities are global to the user, not per app — a Slack id identifies a person regardless of who is asking.",
+        params: { userId: "IdP user id." },
+        successCode: "200",
+        success: LinkedIdentityListSchema,
+    },
+    "post /api/v1/users/{userId}/identities": {
+        summary: "Link an external id to a user",
+        description: "Requires an admin key: a link asserts identity with nothing to prove it, so no app or member may do it. 201 on a new link, 200 when the same pair was already this user's, 409 `already_linked` when it belongs to someone else — an identity is never silently re-pointed.",
+        params: { userId: "IdP user id." },
+        input: LinkIdentityInput,
+        successCode: "201",
+        success: LinkedIdentityCreatedSchema,
+    },
+    "delete /api/v1/users/{userId}/identities/{id}": {
+        summary: "Unlink an external id (idempotent)",
+        description: "Requires an admin key.",
+        params: { userId: "IdP user id.", id: "Linked identity id." },
+        successCode: "200",
+        success: OkSchema,
+    },
+    "get /api/v1/apps/{app}/identities/{provider}/{externalId}": {
+        summary: "Resolve an external id to a user and their permissions in this app",
+        description: "The hot path for an app that hears from someone on another system. Always 200 with a `found` discriminator — a miss is data, and the common case in any shared channel. `permissions` are the user's product permissions for THIS app, computed exactly as the claims hook computes them at token mint, so a Slack message and a browser session from the same person carry the same grants. A user with no membership resolves as found with no permissions.",
+        permission: "identity:resolve",
+        params: { ...APP_PARAM, provider: "The other system, e.g. slack.", externalId: "The id as that system spells it." },
+        successCode: "200",
+        success: IdentityResolutionSchema,
+    },
     "get /api/v1/apps/{app}/audit": {
         summary: "List recent audit entries",
         permission: "audit:read",

package/openapi/idp-api.json

@@ -2326,6 +2326,360 @@
         }
       }
     },
+    "/api/v1/users/{userId}/identities": {
+      "get": {
+        "summary": "List a user's linked identities (their ids on other systems)",
+        "description": "Requires an admin key. Identities are global to the user, not per app — a Slack id identifies a person regardless of who is asking.",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "userId",
+            "in": "path",
+            "required": true,
+            "description": "IdP user id.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$schema": "https://json-schema.org/draft/2020-12/schema",
+                  "type": "object",
+                  "properties": {
+                    "identities": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "string"
+                          },
+                          "userId": {
+                            "type": "string"
+                          },
+                          "provider": {
+                            "type": "string",
+                            "description": "The other system, lowercase — slack, whatsapp, telegram"
+                          },
+                          "externalId": {
+                            "type": "string",
+                            "description": "The id exactly as that system spells it"
+                          },
+                          "label": {
+                            "anyOf": [
+                              {
+                                "type": "string"
+                              },
+                              {
+                                "type": "null"
+                              }
+                            ]
+                          },
+                          "createdAt": {
+                            "type": "string"
+                          }
+                        },
+                        "required": [
+                          "id",
+                          "userId",
+                          "provider",
+                          "externalId",
+                          "label",
+                          "createdAt"
+                        ],
+                        "additionalProperties": false
+                      }
+                    }
+                  },
+                  "required": [
+                    "identities"
+                  ],
+                  "additionalProperties": false
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token"
+          }
+        }
+      },
+      "post": {
+        "summary": "Link an external id to a user",
+        "description": "Requires an admin key: a link asserts identity with nothing to prove it, so no app or member may do it. 201 on a new link, 200 when the same pair was already this user's, 409 `already_linked` when it belongs to someone else — an identity is never silently re-pointed.",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "userId",
+            "in": "path",
+            "required": true,
+            "description": "IdP user id.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$schema": "https://json-schema.org/draft/2020-12/schema",
+                "type": "object",
+                "properties": {
+                  "provider": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "slack, whatsapp, telegram… — normalised to lowercase"
+                  },
+                  "externalId": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The id as that system spells it, e.g. a Slack member id"
+                  },
+                  "label": {
+                    "description": "A human label for the console",
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "provider",
+                  "externalId"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$schema": "https://json-schema.org/draft/2020-12/schema",
+                  "type": "object",
+                  "properties": {
+                    "id": {
+                      "type": "string"
+                    },
+                    "created": {
+                      "type": "boolean",
+                      "description": "false when the same pair was already this user's"
+                    }
+                  },
+                  "required": [
+                    "id",
+                    "created"
+                  ],
+                  "additionalProperties": false
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token"
+          },
+          "405": {
+            "description": "Method not allowed on this resource (see the `Allow` header)"
+          },
+          "409": {
+            "description": "Conflict (already a member, last admin, slug taken, …)"
+          },
+          "422": {
+            "description": "Body failed validation"
+          }
+        }
+      }
+    },
+    "/api/v1/users/{userId}/identities/{id}": {
+      "delete": {
+        "summary": "Unlink an external id (idempotent)",
+        "description": "Requires an admin key.",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "userId",
+            "in": "path",
+            "required": true,
+            "description": "IdP user id.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "Linked identity id.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$schema": "https://json-schema.org/draft/2020-12/schema",
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean",
+                      "const": true
+                    }
+                  },
+                  "required": [
+                    "ok"
+                  ],
+                  "additionalProperties": false
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token"
+          },
+          "405": {
+            "description": "Method not allowed on this resource (see the `Allow` header)"
+          },
+          "409": {
+            "description": "Conflict (already a member, last admin, slug taken, …)"
+          }
+        }
+      }
+    },
+    "/api/v1/apps/{app}/identities/{provider}/{externalId}": {
+      "get": {
+        "summary": "Resolve an external id to a user and their permissions in this app",
+        "description": "The hot path for an app that hears from someone on another system. Always 200 with a `found` discriminator — a miss is data, and the common case in any shared channel. `permissions` are the user's product permissions for THIS app, computed exactly as the claims hook computes them at token mint, so a Slack message and a browser session from the same person carry the same grants. A user with no membership resolves as found with no permissions.",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "app",
+            "in": "path",
+            "required": true,
+            "description": "Application key (oauth_client.metadata.app).",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "provider",
+            "in": "path",
+            "required": true,
+            "description": "The other system, e.g. slack.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "externalId",
+            "in": "path",
+            "required": true,
+            "description": "The id as that system spells it.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$schema": "https://json-schema.org/draft/2020-12/schema",
+                  "anyOf": [
+                    {
+                      "type": "object",
+                      "properties": {
+                        "found": {
+                          "type": "boolean",
+                          "const": true
+                        },
+                        "userId": {
+                          "type": "string"
+                        },
+                        "email": {
+                          "type": "string"
+                        },
+                        "name": {
+                          "anyOf": [
+                            {
+                              "type": "string"
+                            },
+                            {
+                              "type": "null"
+                            }
+                          ]
+                        },
+                        "permissions": {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          },
+                          "description": "The user's product permissions for the asking app; admins get the whole catalog"
+                        }
+                      },
+                      "required": [
+                        "found",
+                        "userId",
+                        "email",
+                        "name",
+                        "permissions"
+                      ],
+                      "additionalProperties": false
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "found": {
+                          "type": "boolean",
+                          "const": false
+                        }
+                      },
+                      "required": [
+                        "found"
+                      ],
+                      "additionalProperties": false
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token"
+          },
+          "403": {
+            "description": "Key lacks the permission / is bound to another app"
+          }
+        }
+      }
+    },
     "/api/v1/apps/{app}/audit": {
       "get": {
         "summary": "List recent audit entries",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@willyim/idp",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Login for apps that don't own identity \u2014 OIDC client, server sessions, and react-router guards against the willy.im IdP",
   "type": "module",
   "main": "./dist/src/index.js",