@willyim/idp 0.6.0 → 0.7.0

package/README.md

@@ -215,7 +215,9 @@ 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
@@ -321,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,
 })
 
@@ -347,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/index.d.ts

@@ -17,6 +17,7 @@ export { createIdp, DEFAULT_SESSION_COOKIE, publicSession, safeNext, type Idp, t
 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,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;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

@@ -17,6 +17,9 @@ export { createIdp, DEFAULT_SESSION_COOKIE, publicSession, safeNext, } from "./s
 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/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;
@@ -43,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;
@@ -74,12 +120,26 @@ 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<{

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;;;;;;;iBASrB,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"),
@@ -77,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) ---
@@ -138,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": {
@@ -421,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/openapi/idp-api.json

@@ -78,6 +78,30 @@
                             },
                             "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": {
@@ -105,6 +129,7 @@
                           "app",
                           "allowSignup",
                           "permissions",
+                          "resourceTypes",
                           "resources",
                           "redirectUris",
                           "disabled",
@@ -291,6 +316,30 @@
                       },
                       "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": {
@@ -318,6 +367,7 @@
                     "app",
                     "allowSignup",
                     "permissions",
+                    "resourceTypes",
                     "resources",
                     "redirectUris",
                     "disabled",
@@ -438,6 +488,30 @@
                       },
                       "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": {
@@ -465,6 +539,7 @@
                     "app",
                     "allowSignup",
                     "permissions",
+                    "resourceTypes",
                     "resources",
                     "redirectUris",
                     "disabled",
@@ -617,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": []
@@ -648,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": [
@@ -671,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
                 }
@@ -2055,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": []
@@ -2090,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.6.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",