@willyim/idp 0.3.0 → 0.4.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
@@ -358,9 +407,14 @@ const { token } = await api.request("post", "/api/v1/admin-keys", {
 //   Authorization: Bearer wim_…
 ```
 
-The IdP's static `ADMIN_API_TOKEN` still works and still grants superadmin, but
-it is break-glass only: one shared secret, no name, no expiry, and no way to
-revoke it short of a redeploy.
+There is no static superadmin secret: every bearer the IdP accepts is a key row
+it issued, so every superadmin action names a revocable credential.
+
+**Break-glass.** If every admin key is lost, recover by writing one bootstrap
+key straight into D1 — insert an `api_key` row with `application_id` NULL and
+`key_hash` set to the SHA-256 hex digest of a token you generate — then use it
+to mint a real key via `POST /api/v1/admin-keys` and revoke the bootstrap row
+through `DELETE /api/v1/admin-keys/{id}`.
 
 The OIDC endpoints are not in that document and never will be: they are
 standards-defined and discovered at runtime from `.well-known`.

package/dist/src/api.d.ts

@@ -42,7 +42,7 @@ export type RequestOptions<P extends string, O> = PathParams<P> & RequestBody<O>
 export type ManagementApiOptions = {
     /** IdP origin — the API lives at the root, not under the `/auth` basepath. */
     baseUrl: string;
-    /** Superadmin `ADMIN_API_TOKEN` or a scoped `wim_…` key. */
+    /** An IdP-level admin key or a per-app scoped `wim_…` key. */
     token: string;
     fetch?: typeof fetch;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAG5B,OAAO,EAEL,KAAK,UAAU,EAEf,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,QAAQ,EACd,MAAM,yBAAyB,CAAA;AAGhC,MAAM,MAAM,MAAM,GAAG,UAAU,CAAA;AAC/B,YAAY,EAAE,QAAQ,EAAE,CAAA;AAExB,6EAA6E;AAC7E,KAAK,UAAU,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GACnE;IAAE,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,GACtB;IAAE,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,CAAA;AAEjD,KAAK,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;CAAE,GACpB;IAAE,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,CAAA;AAExB,mEAAmE;AACnE,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,OAAO,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,CAAA;CAAE,GACzE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GACX,KAAK,CAAA;AAET,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,GAC7D,WAAW,CAAC,CAAC,CAAC,GAAG;IACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAA;IAC7D,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,CAAA;AAEH,MAAM,MAAM,oBAAoB,GAAG;IACjC,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAA;IACf,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;CACrB,CAAA;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB;YAK/C,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,UAC3C,CAAC,QACH,CAAC,SACD,cAAc,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAC1C,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;EAuC9C;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAA"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAG5B,OAAO,EAEL,KAAK,UAAU,EAEf,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,QAAQ,EACd,MAAM,yBAAyB,CAAA;AAGhC,MAAM,MAAM,MAAM,GAAG,UAAU,CAAA;AAC/B,YAAY,EAAE,QAAQ,EAAE,CAAA;AAExB,6EAA6E;AAC7E,KAAK,UAAU,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GACnE;IAAE,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,GACtB;IAAE,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,CAAA;AAEjD,KAAK,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;CAAE,GACpB;IAAE,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,CAAA;AAExB,mEAAmE;AACnE,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,OAAO,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,CAAA;CAAE,GACzE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GACX,KAAK,CAAA;AAET,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,GAC7D,WAAW,CAAC,CAAC,CAAC,GAAG;IACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAA;IAC7D,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,CAAA;AAEH,MAAM,MAAM,oBAAoB,GAAG;IACjC,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAA;IACf,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;CACrB,CAAA;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB;YAK/C,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,UAC3C,CAAC,QACH,CAAC,SACD,cAAc,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAC1C,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;EAuC9C;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAA"}

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,7 @@ 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 { 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,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,6 @@ 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 { parseDuration } from "./duration.js";
 export { clearCookie, parseCookies, readCookie, serializeCookie, } from "./cookie.js";

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

@@ -219,6 +219,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;;;;;;;;;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;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

@@ -149,6 +149,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/openapi.js

@@ -16,7 +16,7 @@ import { lookup, operations } from "./operations.js";
  */
 const json = (schema) => z.toJSONSchema(schema);
 const jsonInput = (schema) => z.toJSONSchema(schema, { io: "input" });
-const DESCRIPTION = "Management API for the willy.im identity provider. Authenticate with `Authorization: Bearer <token>`. Two kinds of token: the superadmin `ADMIN_API_TOKEN` (every app) and per-app **scoped API keys** minted in the admin console (one app, a fixed permission set). The cross-app endpoints below require the superadmin token.";
+const DESCRIPTION = "Management API for the willy.im identity provider. Authenticate with `Authorization: Bearer <token>`. Two kinds of bearer, both `wim_` keys: IdP-level **admin keys** (every permission on every app, minted at `/api/v1/admin-keys`) and per-app **scoped keys** minted in the admin console (one app, a fixed permission set). The cross-app endpoints below require an admin key.";
 function pathParamNames(path) {
     return [...path.matchAll(/\{([^}]+)\}/g)].map((match) => match[1]);
 }
@@ -45,8 +45,8 @@ function operationObject(method, path, def) {
         summary: def.summary,
         description: def.description ??
             (scoped
-                ? `Requires \`${def.permission}\` on the path app (or the superadmin token).`
-                : "Requires the superadmin token."),
+                ? `Requires \`${def.permission}\` on the path app (or an admin key).`
+                : "Requires an admin key."),
         security: [{ bearerAuth: [] }],
         ...(parameters.length ? { parameters } : {}),
         ...(def.input
@@ -102,7 +102,7 @@ export function buildOpenApiDocument(input) {
                 bearerAuth: {
                     type: "http",
                     scheme: "bearer",
-                    description: "Superadmin ADMIN_API_TOKEN or a scoped API key (wim_…).",
+                    description: "An IdP-level admin key or a per-app scoped key (wim_…).",
                 },
             },
         },

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

@@ -51,7 +51,7 @@ export declare const operations: {
     };
     readonly "post /api/v1/applications": {
         readonly summary: "Register an application (client secret returned once)";
-        readonly description: "Requires the superadmin token. Creating an application is an IdP-level act — there is no app to scope a permission to yet.";
+        readonly description: "Requires an admin key. Creating an application is an IdP-level act — there is no app to scope a permission to yet.";
         readonly input: z.ZodObject<{
             name: z.ZodString;
             app: z.ZodString;
@@ -174,7 +174,7 @@ export declare const operations: {
     };
     readonly "post /api/v1/apps/{app}/keys": {
         readonly summary: "Mint a scoped management API key (plaintext returned once)";
-        readonly description: "Requires `apikey:create` on the path app (or the superadmin token). The requested permissions must be a subset of the caller's own, otherwise 403 `permissions_exceed_caller` — without that rule any key holding `apikey:create` could mint itself a more powerful successor.";
+        readonly description: "Requires `apikey:create` on the path app (or an admin key). The requested permissions must be a subset of the caller's own, otherwise 403 `permissions_exceed_caller` — without that rule any key holding `apikey:create` could mint itself a more powerful successor.";
         readonly permission: "apikey:create";
         readonly params: {
             readonly app: "Application key (oauth_client.metadata.app).";
@@ -205,7 +205,7 @@ export declare const operations: {
     };
     readonly "get /api/v1/admin-keys": {
         readonly summary: "List IdP-level admin keys (never the hashes)";
-        readonly description: "Requires the superadmin token or an admin key. Admin keys are `api_key` rows with no application scope, so they hold every permission on every app.";
+        readonly description: "Requires an admin key. Admin keys are `api_key` rows with no application scope, so they hold every permission on every app.";
         readonly successCode: "200";
         readonly success: z.ZodObject<{
             keys: z.ZodArray<z.ZodObject<{
@@ -226,7 +226,7 @@ export declare const operations: {
     };
     readonly "post /api/v1/admin-keys": {
         readonly summary: "Mint an IdP-level admin key (plaintext returned once)";
-        readonly description: "Requires the superadmin token or an admin key. Mint one per agent: unlike the static ADMIN_API_TOKEN, an admin key has a name, an optional expiry, a revoke switch, and its own `adminkey:<id>` identity in the audit log.";
+        readonly description: "Requires an admin key. Mint one per agent: an admin key has a name, an optional expiry, a revoke switch, and its own `adminkey:<id>` identity in the audit log, so every superadmin action is attributable.";
         readonly input: z.ZodObject<{
             name: z.ZodString;
             expiresAt: z.ZodOptional<z.ZodISODateTime>;
@@ -471,6 +471,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 = {
@@ -19,7 +19,7 @@ export const operations = {
     },
     "post /api/v1/applications": {
         summary: "Register an application (client secret returned once)",
-        description: "Requires the superadmin token. Creating an application is an IdP-level act — there is no app to scope a permission to yet.",
+        description: "Requires an admin key. Creating an application is an IdP-level act — there is no app to scope a permission to yet.",
         input: CreateApplicationInput,
         successCode: "201",
         success: ApplicationCreatedSchema,
@@ -75,7 +75,7 @@ export const operations = {
     },
     "post /api/v1/apps/{app}/keys": {
         summary: "Mint a scoped management API key (plaintext returned once)",
-        description: "Requires `apikey:create` on the path app (or the superadmin token). The requested permissions must be a subset of the caller's own, otherwise 403 `permissions_exceed_caller` — without that rule any key holding `apikey:create` could mint itself a more powerful successor.",
+        description: "Requires `apikey:create` on the path app (or an admin key). The requested permissions must be a subset of the caller's own, otherwise 403 `permissions_exceed_caller` — without that rule any key holding `apikey:create` could mint itself a more powerful successor.",
         permission: "apikey:create",
         params: APP_PARAM,
         input: CreateApiKeyInput,
@@ -92,13 +92,13 @@ export const operations = {
     },
     "get /api/v1/admin-keys": {
         summary: "List IdP-level admin keys (never the hashes)",
-        description: "Requires the superadmin token or an admin key. Admin keys are `api_key` rows with no application scope, so they hold every permission on every app.",
+        description: "Requires an admin key. Admin keys are `api_key` rows with no application scope, so they hold every permission on every app.",
         successCode: "200",
         success: AdminKeyListSchema,
     },
     "post /api/v1/admin-keys": {
         summary: "Mint an IdP-level admin key (plaintext returned once)",
-        description: "Requires the superadmin token or an admin key. Mint one per agent: unlike the static ADMIN_API_TOKEN, an admin key has a name, an optional expiry, a revoke switch, and its own `adminkey:<id>` identity in the audit log.",
+        description: "Requires an admin key. Mint one per agent: an admin key has a name, an optional expiry, a revoke switch, and its own `adminkey:<id>` identity in the audit log, so every superadmin action is attributable.",
         input: CreateAdminKeyInput,
         successCode: "201",
         success: AdminKeyCreatedSchema,
@@ -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

@@ -3,7 +3,7 @@
   "info": {
     "title": "willy.im IdP — Management API",
     "version": "1.0.0",
-    "description": "Management API for the willy.im identity provider. Authenticate with `Authorization: Bearer <token>`. Two kinds of token: the superadmin `ADMIN_API_TOKEN` (every app) and per-app **scoped API keys** minted in the admin console (one app, a fixed permission set). The cross-app endpoints below require the superadmin token."
+    "description": "Management API for the willy.im identity provider. Authenticate with `Authorization: Bearer <token>`. Two kinds of bearer, both `wim_` keys: IdP-level **admin keys** (every permission on every app, minted at `/api/v1/admin-keys`) and per-app **scoped keys** minted in the admin console (one app, a fixed permission set). The cross-app endpoints below require an admin key."
   },
   "servers": [
     {
@@ -15,7 +15,7 @@
       "bearerAuth": {
         "type": "http",
         "scheme": "bearer",
-        "description": "Superadmin ADMIN_API_TOKEN or a scoped API key (wim_…)."
+        "description": "An IdP-level admin key or a per-app scoped key (wim_…)."
       }
     }
   },
@@ -23,7 +23,7 @@
     "/api/v1/applications": {
       "get": {
         "summary": "List registered applications",
-        "description": "Requires the superadmin token.",
+        "description": "Requires an admin key.",
         "security": [
           {
             "bearerAuth": []
@@ -121,7 +121,7 @@
       },
       "post": {
         "summary": "Register an application (client secret returned once)",
-        "description": "Requires the superadmin token. Creating an application is an IdP-level act — there is no app to scope a permission to yet.",
+        "description": "Requires an admin key. Creating an application is an IdP-level act — there is no app to scope a permission to yet.",
         "security": [
           {
             "bearerAuth": []
@@ -222,7 +222,7 @@
     "/api/v1/applications/{clientId}": {
       "get": {
         "summary": "Get one application",
-        "description": "Requires `app:read` on the path app (or the superadmin token).",
+        "description": "Requires `app:read` on the path app (or an admin key).",
         "security": [
           {
             "bearerAuth": []
@@ -325,7 +325,7 @@
       },
       "patch": {
         "summary": "Update an application",
-        "description": "Requires `app:update` on the path app (or the superadmin token).",
+        "description": "Requires `app:update` on the path app (or an admin key).",
         "security": [
           {
             "bearerAuth": []
@@ -465,7 +465,7 @@
       },
       "delete": {
         "summary": "Deregister an application",
-        "description": "Requires `app:delete` on the path app (or the superadmin token).",
+        "description": "Requires `app:delete` on the path app (or an admin key).",
         "security": [
           {
             "bearerAuth": []
@@ -525,7 +525,7 @@
     "/api/v1/applications/{clientId}/rotate-secret": {
       "post": {
         "summary": "Rotate the client secret (returned once; the old one stops working)",
-        "description": "Requires `app:update` on the path app (or the superadmin token).",
+        "description": "Requires `app:update` on the path app (or an admin key).",
         "security": [
           {
             "bearerAuth": []
@@ -585,7 +585,7 @@
     "/api/v1/apps/{app}/permissions": {
       "put": {
         "summary": "Replace the app's product-permission catalog",
-        "description": "Requires `app:update` on the path app (or the superadmin token).",
+        "description": "Requires `app:update` on the path app (or an admin key).",
         "security": [
           {
             "bearerAuth": []
@@ -673,7 +673,7 @@
     "/api/v1/apps/{app}/keys": {
       "get": {
         "summary": "List scoped management API keys (never the hashes)",
-        "description": "Requires `apikey:read` on the path app (or the superadmin token).",
+        "description": "Requires `apikey:read` on the path app (or an admin key).",
         "security": [
           {
             "bearerAuth": []
@@ -796,7 +796,7 @@
       },
       "post": {
         "summary": "Mint a scoped management API key (plaintext returned once)",
-        "description": "Requires `apikey:create` on the path app (or the superadmin token). The requested permissions must be a subset of the caller's own, otherwise 403 `permissions_exceed_caller` — without that rule any key holding `apikey:create` could mint itself a more powerful successor.",
+        "description": "Requires `apikey:create` on the path app (or an admin key). The requested permissions must be a subset of the caller's own, otherwise 403 `permissions_exceed_caller` — without that rule any key holding `apikey:create` could mint itself a more powerful successor.",
         "security": [
           {
             "bearerAuth": []
@@ -899,7 +899,7 @@
     "/api/v1/apps/{app}/keys/{id}": {
       "delete": {
         "summary": "Revoke a scoped management API key (idempotent)",
-        "description": "Requires `apikey:revoke` on the path app (or the superadmin token).",
+        "description": "Requires `apikey:revoke` on the path app (or an admin key).",
         "security": [
           {
             "bearerAuth": []
@@ -967,7 +967,7 @@
     "/api/v1/admin-keys": {
       "get": {
         "summary": "List IdP-level admin keys (never the hashes)",
-        "description": "Requires the superadmin token or an admin key. Admin keys are `api_key` rows with no application scope, so they hold every permission on every app.",
+        "description": "Requires an admin key. Admin keys are `api_key` rows with no application scope, so they hold every permission on every app.",
         "security": [
           {
             "bearerAuth": []
@@ -1068,7 +1068,7 @@
       },
       "post": {
         "summary": "Mint an IdP-level admin key (plaintext returned once)",
-        "description": "Requires the superadmin token or an admin key. Mint one per agent: unlike the static ADMIN_API_TOKEN, an admin key has a name, an optional expiry, a revoke switch, and its own `adminkey:<id>` identity in the audit log.",
+        "description": "Requires an admin key. Mint one per agent: an admin key has a name, an optional expiry, a revoke switch, and its own `adminkey:<id>` identity in the audit log, so every superadmin action is attributable.",
         "security": [
           {
             "bearerAuth": []
@@ -1206,7 +1206,7 @@
     "/api/v1/users": {
       "get": {
         "summary": "List users",
-        "description": "Requires the superadmin token.",
+        "description": "Requires an admin key.",
         "security": [
           {
             "bearerAuth": []
@@ -1277,7 +1277,7 @@
     "/api/v1/workspaces": {
       "get": {
         "summary": "List workspaces",
-        "description": "Requires the superadmin token.",
+        "description": "Requires an admin key.",
         "security": [
           {
             "bearerAuth": []
@@ -1348,7 +1348,7 @@
     "/api/v1/apps/{app}/members": {
       "get": {
         "summary": "List app members",
-        "description": "Requires `member:read` on the path app (or the superadmin token).",
+        "description": "Requires `member:read` on the path app (or an admin key).",
         "security": [
           {
             "bearerAuth": []
@@ -1438,7 +1438,7 @@
       },
       "post": {
         "summary": "Add or invite a member",
-        "description": "Requires `member:invite` on the path app (or the superadmin token).",
+        "description": "Requires `member:invite` on the path app (or an admin key).",
         "security": [
           {
             "bearerAuth": []
@@ -1537,7 +1537,7 @@
     "/api/v1/apps/{app}/members/{userId}": {
       "patch": {
         "summary": "Update a member's role + permissions",
-        "description": "Requires `member:manage` on the path app (or the superadmin token).",
+        "description": "Requires `member:manage` on the path app (or an admin key).",
         "security": [
           {
             "bearerAuth": []
@@ -1633,7 +1633,7 @@
       },
       "delete": {
         "summary": "Remove a member",
-        "description": "Requires `member:manage` on the path app (or the superadmin token).",
+        "description": "Requires `member:manage` on the path app (or an admin key).",
         "security": [
           {
             "bearerAuth": []
@@ -1698,7 +1698,7 @@
     "/api/v1/apps/{app}/workspaces": {
       "get": {
         "summary": "List app workspaces",
-        "description": "Requires `workspace:read` on the path app (or the superadmin token).",
+        "description": "Requires `workspace:read` on the path app (or an admin key).",
         "security": [
           {
             "bearerAuth": []
@@ -1781,7 +1781,7 @@
       },
       "post": {
         "summary": "Create a workspace",
-        "description": "Requires `workspace:create` on the path app (or the superadmin token).",
+        "description": "Requires `workspace:create` on the path app (or an admin key).",
         "security": [
           {
             "bearerAuth": []
@@ -1874,7 +1874,7 @@
     "/api/v1/apps/{app}/user-keys": {
       "get": {
         "summary": "List end-user API keys",
-        "description": "Requires `userkey:read` on the path app (or the superadmin token).",
+        "description": "Requires `userkey:read` on the path app (or an admin key).",
         "security": [
           {
             "bearerAuth": []
@@ -2018,7 +2018,7 @@
       },
       "post": {
         "summary": "Mint an end-user API key (plaintext returned once)",
-        "description": "Requires `userkey:create` on the path app (or the superadmin token).",
+        "description": "Requires `userkey:create` on the path app (or an admin key).",
         "security": [
           {
             "bearerAuth": []
@@ -2128,7 +2128,7 @@
     "/api/v1/apps/{app}/user-keys/validate": {
       "post": {
         "summary": "Validate a presented end-user key (200 + valid discriminator)",
-        "description": "Requires `userkey:validate` on the path app (or the superadmin token).",
+        "description": "Requires `userkey:validate` on the path app (or an admin key).",
         "security": [
           {
             "bearerAuth": []
@@ -2264,7 +2264,7 @@
     "/api/v1/apps/{app}/user-keys/{id}": {
       "delete": {
         "summary": "Revoke an end-user API key (idempotent)",
-        "description": "Requires `userkey:revoke` on the path app (or the superadmin token).",
+        "description": "Requires `userkey:revoke` on the path app (or an admin key).",
         "security": [
           {
             "bearerAuth": []
@@ -2326,10 +2326,364 @@
         }
       }
     },
+    "/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",
-        "description": "Requires `audit:read` on the path app (or the superadmin token).",
+        "description": "Requires `audit:read` on the path app (or an admin key).",
         "security": [
           {
             "bearerAuth": []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@willyim/idp",
-  "version": "0.3.0",
+  "version": "0.4.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",