@willyim/idp 0.5.0 → 0.7.0

package/README.md

@@ -82,7 +82,8 @@ return requestHandler(request, {
 })
 ```
 
-**`app/routes/auth.$.tsx`** — serves `/auth/login`, `/auth/callback`, `/auth/logout`:
+**`app/routes/auth.$.tsx`** — serves `/auth/login`, `/auth/callback`, `/auth/logout`
+and `/auth/me`:
 
 ```ts
 import { createAuthRoute } from "@willyim/idp/react-router"
@@ -110,6 +111,17 @@ export async function loader(args: Route.LoaderArgs) {
 }
 ```
 
+For code that can't reach a loader — a client-only route, a widget mounted
+outside the router, a fetch from a worker — the same route answers `/auth/me`:
+
+```ts
+const { user } = await fetch("/auth/me").then((r) => r.json())
+// 200 { user: PublicSession }  ·  401 { user: null }
+```
+
+A server-rendered page should keep using `requireSession`: `/auth/me` is the
+same data, one network hop later.
+
 ## Env
 
 | Var                                   | Purpose                  |
@@ -203,7 +215,21 @@ type Session = {
 }
 ```
 
-`can()` matches exactly, and honours `resource:*` and `*` grants.
+`can()` matches exactly, and honours `resource:*` and `*` grants — so a grant of
+`kirby:*` covers `kirby:read` and a per-instance `kirby:thread:t_7f3a` alike
+(see [Resource-scoped grants](#resource-scoped-grants)).
+
+`image` is effectively always set against the willy.im IdP: it renders a
+deterministic [blobatar](https://blobatar.dev) for anyone who never uploaded a
+picture, so `<img src={session.image} />` needs no fallback of its own. The type
+stays nullable for other issuers. Show `session.name || session.email` — a name
+is a person, an email is a login.
+
+### `publicSession(session)`
+
+`Session` as JSON, without the methods and without the session id — the shape
+that is safe to hand a browser. This is what `/auth/me` (below) returns, and
+what your own `/me` should.
 
 ### `createIdpClient(options)` — the OIDC relying party on its own
 
@@ -297,7 +323,9 @@ const keys = createUserKeys({
 const minted = await keys.create({
   userId: session.userId,
   name: "cli",
-  scopes: ["analytics:read"], // must be in the app's product permission catalog
+  // A declared permission, or `<type>:<id>` for an instance the app lists —
+  // anything else is a 422 (`unknown_scopes` / `unknown_resource`).
+  scopes: ["analytics:read", "kirby:thread:t_7f3a"],
   workspaceId: session.workspaceId,
 })
 
@@ -323,6 +351,61 @@ 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.
 
+## Resource-scoped grants
+
+A permission names a surface (`kirby:read`). When the honest grant is one thing
+inside it — one conversation, one document, one workspace — the app declares a
+resource **type** in its catalog and the grant becomes `<type>:<id>`:
+
+```ts
+await api.request("put", "/api/v1/apps/{app}/permissions", {
+  params: { app: "bender" },
+  body: {
+    permissions: ["kirby:read", "kirby:write"],
+    resourceTypes: [
+      {
+        type: "kirby:thread", // grants compose as kirby:thread:<id>
+        label: "WhatsApp conversation", // what the console calls one
+        list: "https://bender.romo.fyi/idp/resources/kirby-thread",
+      },
+    ],
+  },
+})
+```
+
+The IdP never stores the instances. When someone picks one in the console, or a
+key is minted for one, it GETs the type's `list` URL and reads
+`{ resources: [{ id, label, description? }] }` (`ResourceListSchema` in
+`@willyim/idp/schemas`). The call carries a one-minute JWT the IdP signs with
+its OIDC key — `aud` is the list URL, the permissions claim is
+`idp:resources:list` — which the app verifies exactly as it verifies an MCP
+access token:
+
+```ts
+import { createResourceServer, RESOURCE_LIST_PERMISSION } from "@willyim/idp"
+
+const listing = createResourceServer({
+  issuer: "https://idp.willy.im/auth",
+  resource: "https://bender.romo.fyi/idp/resources/kirby-thread",
+})
+
+const auth = await listing.authenticate(request, { permissions: [RESOURCE_LIST_PERMISSION] })
+if (!auth.ok) return new Response(auth.error, { status: auth.status })
+return Response.json({ resources: threads.map((t) => ({ id: t.handle, label: t.title })) })
+```
+
+`id` is the stable, opaque handle the grant will name — never an alias — and
+is one segment (no colon, no `*`, no whitespace). On the consuming side nothing
+changes: the composed string arrives in `permissions` / `scopes`, and
+`grants(permissions, "kirby:thread:t_7f3a")` is true for that grant, for
+`kirby:*`, and for `*`. App admins hold `<type>:*` for every declared type. A
+grant whose instance later disappears stays on the key and simply matches
+nothing; removing it is a console act, not the app's.
+
+The full contract — token claims, every error shape, what happens when the
+list is unreachable — is in
+[`apps/idp/docs/resource-scopes.md`](../../apps/idp/docs/resource-scopes.md).
+
 ## Linked identities
 
 A user's ids on *other* systems — their Slack member id, their WhatsApp number,

package/dist/src/client.d.ts

@@ -21,7 +21,7 @@ export declare const DEFAULT_SCOPES: readonly IdpScope[];
 export type IdpClientOptions = {
     /**
      * The OIDC issuer, including the basepath the IdP is mounted on:
-     * `https://idp.willy.im/auth` (or a vanity domain, `https://idp.kasso.do/auth`).
+     * `https://idp.willy.im/auth` (or a vanity domain, `https://idp.app1.com/auth`).
      * Discovery is `${issuer}/.well-known/openid-configuration`.
      */
     issuer: string;

package/dist/src/index.d.ts

@@ -13,10 +13,11 @@
  *   @willyim/idp/react-router  the auth route and the loader guards
  */
 export { createIdpClient, createPkce, DEFAULT_SCOPES, IdpError, SUPPORTED_SCOPES, type AuthorizationUrlInput, type Discovery, type IdpClient, type IdpClientOptions, type IdpScope, type Tokens, } from "./client.js";
-export { createIdp, DEFAULT_SESSION_COOKIE, safeNext, type Idp, type IdpOptions, type Session, type SessionOptions, } from "./session.js";
+export { createIdp, DEFAULT_SESSION_COOKIE, publicSession, safeNext, type Idp, type IdpOptions, type PublicSession, type Session, type SessionOptions, } from "./session.js";
 export { memorySessions, type MemorySessionStore, type SessionRecord, type SessionStore, } from "./store.js";
 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 { RESOURCE_ID_RE, RESOURCE_LIST_PERMISSION, RESOURCE_LIST_TOKEN_TTL_S, RESOURCE_TYPE_RE, ResourceInstanceSchema, ResourceListSchema, ResourceTypeInput, ResourceTypeSchema, } from "./schemas/index.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";

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,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"}
+{"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,aAAa,EACb,QAAQ,EACR,KAAK,GAAG,EACR,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,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;AAIjB,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,yBAAyB,EACzB,gBAAgB,EAChB,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,oBAAoB,CAAA;AAE3B,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

@@ -13,10 +13,13 @@
  *   @willyim/idp/react-router  the auth route and the loader guards
  */
 export { createIdpClient, createPkce, DEFAULT_SCOPES, IdpError, SUPPORTED_SCOPES, } from "./client.js";
-export { createIdp, DEFAULT_SESSION_COOKIE, safeNext, } from "./session.js";
+export { createIdp, DEFAULT_SESSION_COOKIE, publicSession, safeNext, } from "./session.js";
 export { memorySessions, } from "./store.js";
 export { grants, normalizeClaims, PERMISSIONS_CLAIM, WORKSPACES_CLAIM, } from "./claims.js";
 export { createManagementApi, } from "./api.js";
+// Resource-scoped grants: the permission the IdP's listing token carries, and
+// the shapes of a type and an instance. The full set lives in ./schemas.
+export { RESOURCE_ID_RE, RESOURCE_LIST_PERMISSION, RESOURCE_LIST_TOKEN_TTL_S, RESOURCE_TYPE_RE, ResourceInstanceSchema, ResourceListSchema, ResourceTypeInput, ResourceTypeSchema, } from "./schemas/index.js";
 export { createUserKeys, readApiKey, } from "./user-keys.js";
 export { createIdentities, } from "./identities.js";
 export { createResourceServer, } from "./resource-server.js";

package/dist/src/react-router/index.d.ts

@@ -9,6 +9,9 @@
  *   const session = await requireSession(args)
  *   const session = await requirePermission(args, "admin")
  *
+ *   // from the browser, when there's no loader to read
+ *   await fetch("/auth/me").then((r) => r.json())  // { user: PublicSession | null }
+ *
  * No react-router import: the adapter only ever produces `Response`s and
  * functions, both of which react-router already understands. That keeps the
  * subpath dependency-free too, and makes it usable from any framework whose

package/dist/src/react-router/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react-router/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAGjD,4EAA4E;AAC5E,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CAC5C,CAAA;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,SAAS,KAAK,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;AAEjE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAA;CAC3C,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,gBAAqB;mBA+ChE,SAAS;mBACT,SAAS;EAE3B;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,GAAG,CAAA;IACT,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oCAAoC;IACpC,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB,CAAA;AAED,kFAAkF;AAClF,wBAAsB,UAAU,CAC9B,IAAI,EAAE,SAAS,EACf,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAEzB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,SAAS,EACf,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,SAAS,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,OAAO,CAAC,CAMlB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react-router/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAGjD,4EAA4E;AAC5E,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CAC5C,CAAA;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,SAAS,KAAK,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;AAEjE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAA;CAC3C,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,gBAAqB;mBAmEhE,SAAS;mBACT,SAAS;EAE3B;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,GAAG,CAAA;IACT,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oCAAoC;IACpC,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB,CAAA;AAED,kFAAkF;AAClF,wBAAsB,UAAU,CAC9B,IAAI,EAAE,SAAS,EACf,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAEzB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,SAAS,EACf,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,SAAS,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,OAAO,CAAC,CAMlB"}

package/dist/src/react-router/index.js

@@ -9,12 +9,15 @@
  *   const session = await requireSession(args)
  *   const session = await requirePermission(args, "admin")
  *
+ *   // from the browser, when there's no loader to read
+ *   await fetch("/auth/me").then((r) => r.json())  // { user: PublicSession | null }
+ *
  * No react-router import: the adapter only ever produces `Response`s and
  * functions, both of which react-router already understands. That keeps the
  * subpath dependency-free too, and makes it usable from any framework whose
  * handlers take a `Request`.
  */
-import { safeNext } from "../session.js";
+import { publicSession, safeNext } from "../session.js";
 /**
  * Serves `/auth/login`, `/auth/callback` and `/auth/logout` from a single splat
  * route. `loader` covers the GET navigations; `action` covers a POSTed logout
@@ -57,6 +60,26 @@ export function createAuthRoute(getIdp, options = {}) {
             // outlives the app's.
             return redirect(endSession ?? redirectTo, headers);
         }
+        // The session as JSON, for the code that can't reach a loader: a client-only
+        // route, a widget mounted outside the router, a fetch from a worker. A
+        // server-rendered page should keep reading `requireSession` — this is the
+        // same data one network hop later.
+        if (action === "me") {
+            const session = await idp.getSession(args.request);
+            const headers = new Headers({
+                "content-type": "application/json",
+                // Per-user and revocable — never let a shared cache hold it.
+                "cache-control": "no-store, private",
+            });
+            if (!session) {
+                return new Response(JSON.stringify({ user: null }), { status: 401, headers });
+            }
+            // Polling this keeps a sliding session alive, same as any other request.
+            const renewed = session.renewCookie();
+            if (renewed)
+                headers.append("set-cookie", renewed);
+            return new Response(JSON.stringify({ user: publicSession(session) }), { status: 200, headers });
+        }
         return new Response("not found", { status: 404 });
     }
     return {

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

@@ -10,12 +10,53 @@
  * `../wire.ts`, next to the code that talks to them.
  */
 import { z } from "zod";
+/** A resource type name: colon-separated lowercase segments, no wildcard. */
+export declare const RESOURCE_TYPE_RE: RegExp;
+/** An instance id: the final segment of a grant, so no colon, no `*`, no whitespace. */
+export declare const RESOURCE_ID_RE: RegExp;
+/**
+ * The permission the IdP's listing token carries, so an app can gate its `list`
+ * endpoint with `resourceServer.authenticate(request, { permissions: [...] })`.
+ * Namespaced under `idp:` so it can never collide with an app's own catalog.
+ */
+export declare const RESOURCE_LIST_PERMISSION = "idp:resources:list";
+/** Lifetime of the IdP-signed token that authenticates a listing call. */
+export declare const RESOURCE_LIST_TOKEN_TTL_S = 60;
+export declare const ResourceTypeInput: z.ZodObject<{
+    type: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    list: z.ZodString;
+}, z.core.$strip>;
+export declare const ResourceTypeSchema: z.ZodObject<{
+    type: z.ZodString;
+    label: z.ZodString;
+    list: z.ZodString;
+}, z.core.$strip>;
+/** One instance of a resource type, as the app's `list` endpoint reports it. */
+export declare const ResourceInstanceSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/** The body an app's resource `list` endpoint must answer with. */
+export declare const ResourceListSchema: z.ZodObject<{
+    resources: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export declare const ApplicationSchema: z.ZodObject<{
     clientId: z.ZodString;
     name: z.ZodNullable<z.ZodString>;
     app: z.ZodNullable<z.ZodString>;
     allowSignup: z.ZodBoolean;
     permissions: z.ZodArray<z.ZodString>;
+    resourceTypes: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        label: z.ZodString;
+        list: z.ZodString;
+    }, z.core.$strip>>;
     resources: z.ZodArray<z.ZodString>;
     redirectUris: z.ZodArray<z.ZodString>;
     disabled: z.ZodBoolean;
@@ -25,6 +66,7 @@ export declare const UserSchema: z.ZodObject<{
     id: z.ZodString;
     email: z.ZodString;
     name: z.ZodNullable<z.ZodString>;
+    image: z.ZodString;
     emailVerified: z.ZodBoolean;
     createdAt: z.ZodString;
 }, z.core.$strip>;
@@ -42,6 +84,11 @@ export declare const ApplicationListSchema: z.ZodObject<{
         app: z.ZodNullable<z.ZodString>;
         allowSignup: z.ZodBoolean;
         permissions: z.ZodArray<z.ZodString>;
+        resourceTypes: z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            label: z.ZodString;
+            list: z.ZodString;
+        }, z.core.$strip>>;
         resources: z.ZodArray<z.ZodString>;
         redirectUris: z.ZodArray<z.ZodString>;
         disabled: z.ZodBoolean;
@@ -73,18 +120,33 @@ export declare const UpdateApplicationInput: z.ZodObject<{
 export declare const ClientSecretSchema: z.ZodObject<{
     clientSecret: z.ZodString;
 }, z.core.$strip>;
-/** Replaces the app's product-permission catalog wholesale. */
+/**
+ * Replaces the app's product-permission catalog wholesale — both the flat
+ * permissions and the resource types. Omitting `resourceTypes` clears them,
+ * the same way omitting a permission removes it.
+ */
 export declare const SetAppPermissionsInput: z.ZodObject<{
     permissions: z.ZodArray<z.ZodString>;
+    resourceTypes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        list: z.ZodString;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export declare const AppPermissionsSchema: z.ZodObject<{
     permissions: z.ZodArray<z.ZodString>;
+    resourceTypes: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        label: z.ZodString;
+        list: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const UserListSchema: z.ZodObject<{
     users: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         email: z.ZodString;
         name: z.ZodNullable<z.ZodString>;
+        image: z.ZodString;
         emailVerified: z.ZodBoolean;
         createdAt: z.ZodString;
     }, z.core.$strip>>;

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;;;;;;;;;;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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/schemas/index.ts"],"names":[],"mappings":"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"}

package/dist/src/schemas/index.js

@@ -10,12 +10,60 @@
  * `../wire.ts`, next to the code that talks to them.
  */
 import { z } from "zod";
+// --- Resource-scoped permissions ---
+//
+// A permission names a surface (`kirby:read`). A resource TYPE names a family
+// of permissions over instances the app holds (`kirby:thread` over every
+// conversation), and a grant is the composed string `<type>:<id>` —
+// `kirby:thread:t_7f3a`. The IdP never stores the instances: it asks the app
+// for them, over the `list` URL the type declares, whenever a human picks one
+// or a key is minted. `grants()` is untouched — `kirby:*` and `*` cover every
+// instance the same way they cover `kirby:read`.
+/** A resource type name: colon-separated lowercase segments, no wildcard. */
+export const RESOURCE_TYPE_RE = /^[a-z0-9_-]+(:[a-z0-9_-]+)*$/;
+/** An instance id: the final segment of a grant, so no colon, no `*`, no whitespace. */
+export const RESOURCE_ID_RE = /^[^\s:*]+$/;
+/**
+ * The permission the IdP's listing token carries, so an app can gate its `list`
+ * endpoint with `resourceServer.authenticate(request, { permissions: [...] })`.
+ * Namespaced under `idp:` so it can never collide with an app's own catalog.
+ */
+export const RESOURCE_LIST_PERMISSION = "idp:resources:list";
+/** Lifetime of the IdP-signed token that authenticates a listing call. */
+export const RESOURCE_LIST_TOKEN_TTL_S = 60;
+export const ResourceTypeInput = z.object({
+    type: z
+        .string()
+        .regex(RESOURCE_TYPE_RE, "lowercase segments separated by colons, e.g. kirby:thread")
+        .describe("Permission prefix a grant composes under: `kirby:thread` → `kirby:thread:<id>`"),
+    label: z.string().min(1).optional().describe("Human name for one instance, shown in the console — “WhatsApp conversation”"),
+    list: z
+        .string()
+        .url()
+        .describe("Absolute URL the IdP GETs to enumerate instances. Called with an IdP-signed bearer JWT (aud = this URL); must answer `ResourceListSchema`"),
+});
+export const ResourceTypeSchema = z.object({
+    type: z.string(),
+    label: z.string(),
+    list: z.string(),
+});
+/** One instance of a resource type, as the app's `list` endpoint reports it. */
+export const ResourceInstanceSchema = z.object({
+    id: z.string().regex(RESOURCE_ID_RE).describe("The stable, opaque id the grant will name — a handle, never an alias"),
+    label: z.string().min(1).describe("What a human sees when picking it"),
+    description: z.string().nullable().optional().describe("Secondary line in the picker — kind, size, last activity"),
+});
+/** The body an app's resource `list` endpoint must answer with. */
+export const ResourceListSchema = z.object({ resources: z.array(ResourceInstanceSchema) });
 export const ApplicationSchema = z.object({
     clientId: z.string(),
     name: z.string().nullable(),
     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"),
+    resourceTypes: z
+        .array(ResourceTypeSchema)
+        .describe("Declared resource types — permission families over instances the app holds"),
     resources: z
         .array(z.string())
         .describe("Protected resource URIs (e.g. the app's MCP server) — valid `resource` audiences for access tokens"),
@@ -27,6 +75,9 @@ export const UserSchema = z.object({
     id: z.string(),
     email: z.string(),
     name: z.string().nullable(),
+    image: z
+        .string()
+        .describe("Avatar URL — the user's own picture, or the blobatar the IdP renders for them"),
     emailVerified: z.boolean(),
     createdAt: z.string(),
 });
@@ -74,11 +125,19 @@ export const UpdateApplicationInput = z.object({
 export const ClientSecretSchema = z.object({
     clientSecret: z.string().describe("Plaintext client secret — shown exactly once, never stored"),
 });
-/** Replaces the app's product-permission catalog wholesale. */
+/**
+ * Replaces the app's product-permission catalog wholesale — both the flat
+ * permissions and the resource types. Omitting `resourceTypes` clears them,
+ * the same way omitting a permission removes it.
+ */
 export const SetAppPermissionsInput = z.object({
     permissions: z.array(z.string().min(1)),
+    resourceTypes: z.array(ResourceTypeInput).default([]),
+});
+export const AppPermissionsSchema = z.object({
+    permissions: z.array(z.string()),
+    resourceTypes: z.array(ResourceTypeSchema),
 });
-export const AppPermissionsSchema = z.object({ permissions: z.array(z.string()) });
 export const UserListSchema = z.object({ users: z.array(UserSchema) });
 export const WorkspaceListSchema = z.object({ workspaces: z.array(WorkspaceSchema) });
 // --- Write management API (scoped-key authenticated, per-app) ---
@@ -135,7 +194,10 @@ export const UserApiKeyListSchema = z.object({ keys: z.array(UserApiKeySchema) }
 export const CreateUserApiKeyInput = z.object({
     userId: z.string().min(1),
     name: z.string().min(1),
-    scopes: z.array(z.string()).default([]).describe("Subset of the app's product permission catalog"),
+    scopes: z
+        .array(z.string())
+        .default([])
+        .describe("Declared permissions, or `<type>:<id>` grants over a declared resource type whose instance the app currently lists"),
     workspaceId: z.string().optional(),
     expiresAt: z.iso.datetime().optional().describe("ISO 8601; omit for non-expiring"),
 });

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

@@ -43,6 +43,11 @@ export declare const operations: {
                 app: z.ZodNullable<z.ZodString>;
                 allowSignup: z.ZodBoolean;
                 permissions: z.ZodArray<z.ZodString>;
+                resourceTypes: z.ZodArray<z.ZodObject<{
+                    type: z.ZodString;
+                    label: z.ZodString;
+                    list: z.ZodString;
+                }, z.core.$strip>>;
                 resources: z.ZodArray<z.ZodString>;
                 redirectUris: z.ZodArray<z.ZodString>;
                 disabled: z.ZodBoolean;
@@ -80,6 +85,11 @@ export declare const operations: {
             app: z.ZodNullable<z.ZodString>;
             allowSignup: z.ZodBoolean;
             permissions: z.ZodArray<z.ZodString>;
+            resourceTypes: z.ZodArray<z.ZodObject<{
+                type: z.ZodString;
+                label: z.ZodString;
+                list: z.ZodString;
+            }, z.core.$strip>>;
             resources: z.ZodArray<z.ZodString>;
             redirectUris: z.ZodArray<z.ZodString>;
             disabled: z.ZodBoolean;
@@ -106,6 +116,11 @@ export declare const operations: {
             app: z.ZodNullable<z.ZodString>;
             allowSignup: z.ZodBoolean;
             permissions: z.ZodArray<z.ZodString>;
+            resourceTypes: z.ZodArray<z.ZodObject<{
+                type: z.ZodString;
+                label: z.ZodString;
+                list: z.ZodString;
+            }, z.core.$strip>>;
             resources: z.ZodArray<z.ZodString>;
             redirectUris: z.ZodArray<z.ZodString>;
             disabled: z.ZodBoolean;
@@ -138,6 +153,7 @@ export declare const operations: {
     };
     readonly "put /api/v1/apps/{app}/permissions": {
         readonly summary: "Replace the app's product-permission catalog";
+        readonly description: "Wholesale replace of both halves of the catalog: the flat permissions, and the resource types (`{ type, label, list }`) that per-instance grants such as `kirby:thread:<id>` compose under. The IdP GETs each type's `list` URL — with a 60s IdP-signed JWT whose `aud` is that URL — whenever it needs the instances; it never stores them. Omitting `resourceTypes` clears them. 422 `invalid_resource_type` names a `list` URL that is not absolute https (http is allowed for loopback hosts only).";
         readonly permission: "app:update";
         readonly params: {
             readonly app: "Application key (oauth_client.metadata.app).";
@@ -145,10 +161,20 @@ export declare const operations: {
         readonly notFound: "No application with that app key";
         readonly input: z.ZodObject<{
             permissions: z.ZodArray<z.ZodString>;
+            resourceTypes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                type: z.ZodString;
+                label: z.ZodOptional<z.ZodString>;
+                list: z.ZodString;
+            }, z.core.$strip>>>;
         }, z.core.$strip>;
         readonly successCode: "200";
         readonly success: z.ZodObject<{
             permissions: z.ZodArray<z.ZodString>;
+            resourceTypes: z.ZodArray<z.ZodObject<{
+                type: z.ZodString;
+                label: z.ZodString;
+                list: z.ZodString;
+            }, z.core.$strip>>;
         }, z.core.$strip>;
     };
     readonly "get /api/v1/apps/{app}/keys": {
@@ -262,6 +288,7 @@ export declare const operations: {
                 id: z.ZodString;
                 email: z.ZodString;
                 name: z.ZodNullable<z.ZodString>;
+                image: z.ZodString;
                 emailVerified: z.ZodBoolean;
                 createdAt: z.ZodString;
             }, z.core.$strip>>;
@@ -420,6 +447,7 @@ export declare const operations: {
     };
     readonly "post /api/v1/apps/{app}/user-keys": {
         readonly summary: "Mint an end-user API key (plaintext returned once)";
+        readonly description: "Every scope must be a declared permission or `<declared type>:<id>` for an instance the app currently lists. 422 `unknown_scopes` names scopes the catalog does not declare; 422 `unknown_resource` names `<type>:<id>` grants whose instance the app did not list; 502 `resource_lookup_failed` names the types whose `list` URL could not be read.";
         readonly permission: "userkey:create";
         readonly params: {
             readonly app: "Application key (oauth_client.metadata.app).";

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;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"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmP0B,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

@@ -59,6 +59,7 @@ export const operations = {
     },
     "put /api/v1/apps/{app}/permissions": {
         summary: "Replace the app's product-permission catalog",
+        description: "Wholesale replace of both halves of the catalog: the flat permissions, and the resource types (`{ type, label, list }`) that per-instance grants such as `kirby:thread:<id>` compose under. The IdP GETs each type's `list` URL — with a 60s IdP-signed JWT whose `aud` is that URL — whenever it needs the instances; it never stores them. Omitting `resourceTypes` clears them. 422 `invalid_resource_type` names a `list` URL that is not absolute https (http is allowed for loopback hosts only).",
         permission: "app:update",
         params: APP_PARAM,
         notFound: "No application with that app key",
@@ -179,6 +180,7 @@ export const operations = {
     },
     "post /api/v1/apps/{app}/user-keys": {
         summary: "Mint an end-user API key (plaintext returned once)",
+        description: "Every scope must be a declared permission or `<declared type>:<id>` for an instance the app currently lists. 422 `unknown_scopes` names scopes the catalog does not declare; 422 `unknown_resource` names `<type>:<id>` grants whose instance the app did not list; 502 `resource_lookup_failed` names the types whose `list` URL could not be read.",
         permission: "userkey:create",
         params: APP_PARAM,
         input: CreateUserApiKeyInput,

package/dist/src/session.d.ts

@@ -64,6 +64,26 @@ export type Session = {
      */
     renewCookie(): string | null;
 };
+/**
+ * A `Session` as JSON — the shape that is safe to hand a browser.
+ *
+ * Two deliberate omissions. The methods are gone because they don't serialize.
+ * The session *id* is gone because it is the thing the signed cookie resolves
+ * to: it never needs to be in reach of script, and a projection that leaves it
+ * out can't leak it by accident later.
+ */
+export type PublicSession = {
+    sub: string;
+    email: string;
+    name: string | null;
+    image: string | null;
+    permissions: string[];
+    workspaces: Workspace[];
+    actor: Actor | null;
+    expiresAt: string;
+};
+/** `Session` -> `PublicSession`. What `/auth/me` returns, and what an app's own `/me` should. */
+export declare function publicSession(session: Session): PublicSession;
 export type Idp = ReturnType<typeof createIdp>;
 export declare function createIdp(options: IdpOptions): {
     /** The Layer 0 client, for anything the session layer doesn't wrap. */

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

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/session.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/session.ts"],"names":[],"mappings":"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"}

package/dist/src/session.js

@@ -17,6 +17,19 @@ import { parseDuration } from "./duration.js";
 export const DEFAULT_SESSION_COOKIE = "idp_session";
 /** How long the login handshake may take before its state cookie is stale. */
 const STATE_COOKIE_MAX_AGE_MS = 10 * 60_000;
+/** `Session` -> `PublicSession`. What `/auth/me` returns, and what an app's own `/me` should. */
+export function publicSession(session) {
+    return {
+        sub: session.sub,
+        email: session.email,
+        name: session.name,
+        image: session.image,
+        permissions: session.permissions,
+        workspaces: session.workspaces,
+        actor: session.actor,
+        expiresAt: session.expiresAt.toISOString(),
+    };
+}
 /**
  * What rides in the login state cookie. HMAC-signed, so tampering is caught
  * before this ever parses — the schema is here to catch a cookie left over

package/openapi/idp-api.json

@@ -78,6 +78,37 @@
                             },
                             "description": "The app's declared product-permission catalog"
                           },
+                          "resourceTypes": {
+                            "type": "array",
+                            "items": {
+                              "type": "object",
+                              "properties": {
+                                "type": {
+                                  "type": "string"
+                                },
+                                "label": {
+                                  "type": "string"
+                                },
+                                "list": {
+                                  "type": "string"
+                                }
+                              },
+                              "required": [
+                                "type",
+                                "label",
+                                "list"
+                              ],
+                              "additionalProperties": false
+                            },
+                            "description": "Declared resource types — permission families over instances the app holds"
+                          },
+                          "resources": {
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            },
+                            "description": "Protected resource URIs (e.g. the app's MCP server) — valid `resource` audiences for access tokens"
+                          },
                           "redirectUris": {
                             "type": "array",
                             "items": {
@@ -98,6 +129,8 @@
                           "app",
                           "allowSignup",
                           "permissions",
+                          "resourceTypes",
+                          "resources",
                           "redirectUris",
                           "disabled",
                           "createdAt"
@@ -283,6 +316,37 @@
                       },
                       "description": "The app's declared product-permission catalog"
                     },
+                    "resourceTypes": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "type": {
+                            "type": "string"
+                          },
+                          "label": {
+                            "type": "string"
+                          },
+                          "list": {
+                            "type": "string"
+                          }
+                        },
+                        "required": [
+                          "type",
+                          "label",
+                          "list"
+                        ],
+                        "additionalProperties": false
+                      },
+                      "description": "Declared resource types — permission families over instances the app holds"
+                    },
+                    "resources": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      },
+                      "description": "Protected resource URIs (e.g. the app's MCP server) — valid `resource` audiences for access tokens"
+                    },
                     "redirectUris": {
                       "type": "array",
                       "items": {
@@ -303,6 +367,8 @@
                     "app",
                     "allowSignup",
                     "permissions",
+                    "resourceTypes",
+                    "resources",
                     "redirectUris",
                     "disabled",
                     "createdAt"
@@ -364,6 +430,14 @@
                   },
                   "allowSignup": {
                     "type": "boolean"
+                  },
+                  "resources": {
+                    "description": "Replace the app's protected resource URIs — absolute https, no fragment",
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "format": "uri"
+                    }
                   }
                 }
               }
@@ -414,6 +488,37 @@
                       },
                       "description": "The app's declared product-permission catalog"
                     },
+                    "resourceTypes": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "type": {
+                            "type": "string"
+                          },
+                          "label": {
+                            "type": "string"
+                          },
+                          "list": {
+                            "type": "string"
+                          }
+                        },
+                        "required": [
+                          "type",
+                          "label",
+                          "list"
+                        ],
+                        "additionalProperties": false
+                      },
+                      "description": "Declared resource types — permission families over instances the app holds"
+                    },
+                    "resources": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      },
+                      "description": "Protected resource URIs (e.g. the app's MCP server) — valid `resource` audiences for access tokens"
+                    },
                     "redirectUris": {
                       "type": "array",
                       "items": {
@@ -434,6 +539,8 @@
                     "app",
                     "allowSignup",
                     "permissions",
+                    "resourceTypes",
+                    "resources",
                     "redirectUris",
                     "disabled",
                     "createdAt"
@@ -585,7 +692,7 @@
     "/api/v1/apps/{app}/permissions": {
       "put": {
         "summary": "Replace the app's product-permission catalog",
-        "description": "Requires `app:update` on the path app (or an admin key).",
+        "description": "Wholesale replace of both halves of the catalog: the flat permissions, and the resource types (`{ type, label, list }`) that per-instance grants such as `kirby:thread:<id>` compose under. The IdP GETs each type's `list` URL — with a 60s IdP-signed JWT whose `aud` is that URL — whenever it needs the instances; it never stores them. Omitting `resourceTypes` clears them. 422 `invalid_resource_type` names a `list` URL that is not absolute https (http is allowed for loopback hosts only).",
         "security": [
           {
             "bearerAuth": []
@@ -616,6 +723,34 @@
                       "type": "string",
                       "minLength": 1
                     }
+                  },
+                  "resourceTypes": {
+                    "default": [],
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "type": {
+                          "type": "string",
+                          "pattern": "^[a-z0-9_-]+(:[a-z0-9_-]+)*$",
+                          "description": "Permission prefix a grant composes under: `kirby:thread` → `kirby:thread:<id>`"
+                        },
+                        "label": {
+                          "description": "Human name for one instance, shown in the console — “WhatsApp conversation”",
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        "list": {
+                          "type": "string",
+                          "format": "uri",
+                          "description": "Absolute URL the IdP GETs to enumerate instances. Called with an IdP-signed bearer JWT (aud = this URL); must answer `ResourceListSchema`"
+                        }
+                      },
+                      "required": [
+                        "type",
+                        "list"
+                      ]
+                    }
                   }
                 },
                 "required": [
@@ -639,10 +774,34 @@
                       "items": {
                         "type": "string"
                       }
+                    },
+                    "resourceTypes": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "type": {
+                            "type": "string"
+                          },
+                          "label": {
+                            "type": "string"
+                          },
+                          "list": {
+                            "type": "string"
+                          }
+                        },
+                        "required": [
+                          "type",
+                          "label",
+                          "list"
+                        ],
+                        "additionalProperties": false
+                      }
                     }
                   },
                   "required": [
-                    "permissions"
+                    "permissions",
+                    "resourceTypes"
                   ],
                   "additionalProperties": false
                 }
@@ -1242,6 +1401,10 @@
                               }
                             ]
                           },
+                          "image": {
+                            "type": "string",
+                            "description": "Avatar URL — the user's own picture, or the blobatar the IdP renders for them"
+                          },
                           "emailVerified": {
                             "type": "boolean"
                           },
@@ -1253,6 +1416,7 @@
                           "id",
                           "email",
                           "name",
+                          "image",
                           "emailVerified",
                           "createdAt"
                         ],
@@ -2018,7 +2182,7 @@
       },
       "post": {
         "summary": "Mint an end-user API key (plaintext returned once)",
-        "description": "Requires `userkey:create` on the path app (or an admin key).",
+        "description": "Every scope must be a declared permission or `<declared type>:<id>` for an instance the app currently lists. 422 `unknown_scopes` names scopes the catalog does not declare; 422 `unknown_resource` names `<type>:<id>` grants whose instance the app did not list; 502 `resource_lookup_failed` names the types whose `list` URL could not be read.",
         "security": [
           {
             "bearerAuth": []
@@ -2053,7 +2217,7 @@
                   },
                   "scopes": {
                     "default": [],
-                    "description": "Subset of the app's product permission catalog",
+                    "description": "Declared permissions, or `<type>:<id>` grants over a declared resource type whose instance the app currently lists",
                     "type": "array",
                     "items": {
                       "type": "string"

package/package.json

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