@substrat-run/contracts 0.116.0 → 0.118.0

package/dist/auth-delivery.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The delivered-config key that tells a vertical its issuer is SHARED with other clients
+ * (#1683): `"true"` when the app signs in at one of its team's auth-servers, `""` (or
+ * absent) otherwise. The dashboard writes it; `@substrat-run/vertical-auth` reads it.
+ *
+ * A team auth-server is one issuer with one JWKS for every client the team has, plus any
+ * that registered themselves dynamically. So a bearer that verifies there says who signed
+ * it, not whom it is for, and a vertical on such an issuer must accept only its OWN
+ * tokens. An issuer an operator configured by hand is theirs, and its knob is the
+ * delivered `audience`, so the vertical leaves those exactly as they were.
+ *
+ * A key of its own rather than a field inside `substrat:auth`: delivery is an upsert per
+ * key, so the dashboard can converge an existing install on this one fact without
+ * re-delivering, and therefore without reading back, the client secret stored beside it.
+ */
+export declare const SHARED_ISSUER_CONFIG_KEY = "substrat:auth:shared-issuer";
+//# sourceMappingURL=auth-delivery.d.ts.map

package/dist/auth-delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-delivery.d.ts","sourceRoot":"","sources":["../src/auth-delivery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,wBAAwB,gCAAgC,CAAC"}

package/dist/auth-delivery.js

@@ -0,0 +1,17 @@
+/**
+ * The delivered-config key that tells a vertical its issuer is SHARED with other clients
+ * (#1683): `"true"` when the app signs in at one of its team's auth-servers, `""` (or
+ * absent) otherwise. The dashboard writes it; `@substrat-run/vertical-auth` reads it.
+ *
+ * A team auth-server is one issuer with one JWKS for every client the team has, plus any
+ * that registered themselves dynamically. So a bearer that verifies there says who signed
+ * it, not whom it is for, and a vertical on such an issuer must accept only its OWN
+ * tokens. An issuer an operator configured by hand is theirs, and its knob is the
+ * delivered `audience`, so the vertical leaves those exactly as they were.
+ *
+ * A key of its own rather than a field inside `substrat:auth`: delivery is an upsert per
+ * key, so the dashboard can converge an existing install on this one fact without
+ * re-delivering, and therefore without reading back, the client secret stored beside it.
+ */
+export const SHARED_ISSUER_CONFIG_KEY = 'substrat:auth:shared-issuer';
+//# sourceMappingURL=auth-delivery.js.map

package/dist/auth-delivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-delivery.js","sourceRoot":"","sources":["../src/auth-delivery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,6BAA6B,CAAC"}

package/dist/capability.d.ts

@@ -0,0 +1,243 @@
+import { z } from 'zod';
+/**
+ * Capabilities (#1672) — authority carried by a SECRET rather than held by a principal.
+ *
+ * The permission checker reasons about principals, and a link share is authority held by
+ * whoever has the URL: nobody the checker knows. #97 solved the neighbouring case for
+ * connectors by letting the connection BE an actor; this does the same for a secret. A
+ * capability is a directory row, the row names what it may do, and the holder of its
+ * secret acts as `{ capability: <id> }` — resolved by the checker, recorded on the event,
+ * refused into the denial log, like any other actor.
+ *
+ * It is a building block rather than a link-share feature. The repo carried three
+ * hand-built "authority carried by a secret" mechanisms (owner claim links, member
+ * invites, the dashboard's signed tokens), each with its own table and a code path outside
+ * the checker, none of them on the spine as authority. So the shape here has what those
+ * need even where a link share does not: a use limit beside the expiry, and a `become`
+ * mode for "exercising this binds that principal".
+ *
+ * **Directory-backed, never self-contained.** The checker reads the row on every check, so
+ * revoking one is the next read, and every exchange is a counted, recorded use. Only the
+ * secret's SHA-256 is ever stored; the secret itself leaves the kernel once, in the mint's
+ * return value.
+ *
+ * **A use is an exchange, not an invocation.** The secret is presented once, traded for a
+ * session cookie (so it does not live in history or `Referer`), and the session then acts
+ * until the capability expires or is revoked. A read-only share makes dozens of calls per
+ * page load, and a single-use invite would otherwise be spent by its own redemption — so
+ * `maxUses` bounds how many browsers may hold a capability, not how many reads they make.
+ */
+/** What every minted secret starts with — so a secret scanner can recognise a leaked one. */
+export declare const CAPABILITY_SECRET_PREFIX = "sbcap_";
+/** What every session token an exchange hands out starts with. */
+export declare const CAPABILITY_SESSION_PREFIX = "sbses_";
+/** How long a session outlives its exchange, at most — never past the capability itself. */
+export declare const CAPABILITY_SESSION_TTL_MS: number;
+/** The most keys one capability may carry. A link that needs more is a role. */
+export declare const CAPABILITY_PERMISSIONS_MAX = 16;
+/** The most operations one capability's allowlist may name. */
+export declare const CAPABILITY_OPERATIONS_MAX = 32;
+/** An optional operator-facing name for a capability ("client review link"). Never a secret. */
+export declare const capabilityLabel: z.ZodString;
+/**
+ * (Not `capabilityGrant` — that older name in `permission.ts` is an entity-narrowed grant
+ * to a PRINCIPAL, and predates this module.)
+ *
+ * What an `act` capability may do: ONE entity and everything beneath it through declared
+ * parent edges, specific keys on that subtree, and optionally an allowlist of operations.
+ *
+ * The keys are the authority — each is checked against the entity exactly as an
+ * entity-narrowed grant would be, which is how grants already travel. `operations`
+ * narrows on top of them and never widens: an operation outside the list is refused at
+ * the door before its handler runs, however much the keys would have allowed. A
+ * capability never holds node-level authority, so an operation whose only check is a
+ * node-level one refuses it.
+ */
+export declare const capabilityAuthority: z.ZodObject<{
+    entity: z.ZodObject<{
+        entityType: z.ZodString;
+        entityId: z.ZodString;
+    }, z.core.$strip>;
+    permissions: z.ZodArray<z.core.$ZodBranded<z.ZodString, "PermissionKey", "out">>;
+    operations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type CapabilityAuthority = z.infer<typeof capabilityAuthority>;
+/**
+ * What a MODULE may mint (`ctx.capabilities.mint`) — always an `act` capability.
+ *
+ * `expiresAt` absent means no expiry; `maxUses` absent means unlimited exchanges. Both are
+ * a vertical's call: "anyone with the link" is how most sharing works, and a link share
+ * that must die on Friday says so. Neither widens authority — the minter's own is
+ * re-checked on every use.
+ */
+export declare const capabilityMintInput: z.ZodObject<{
+    entity: z.ZodObject<{
+        entityType: z.ZodString;
+        entityId: z.ZodString;
+    }, z.core.$strip>;
+    permissions: z.ZodArray<z.core.$ZodBranded<z.ZodString, "PermissionKey", "out">>;
+    operations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    expiresAt: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "Instant", "out">>;
+    maxUses: z.ZodOptional<z.ZodNumber>;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CapabilityMintInput = z.infer<typeof capabilityMintInput>;
+/**
+ * What the PLATFORM may mint (`HostAdmin.mintCapability`) — a `become` capability:
+ * exchanging it yields a principal instead of a session, the shape an owner claim link and
+ * a member invite are ("whoever opens this becomes that seat").
+ *
+ * Platform-only in this first cut, deliberately. `become` is impersonation by another name
+ * — the holder acquires everything the principal holds — so the bound on who may mint one
+ * from module code is designed with the invite and claim migrations, not guessed here.
+ * Expiry and a use limit are REQUIRED for the same reason: an unbounded `become` is a
+ * standing credential for a person.
+ */
+export declare const becomeCapabilityInput: z.ZodObject<{
+    principal: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+    expiresAt: z.core.$ZodBranded<z.ZodString, "Instant", "out">;
+    maxUses: z.ZodNumber;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type BecomeCapabilityInput = z.infer<typeof becomeCapabilityInput>;
+/**
+ * Who minted or revoked a capability: the principal whose operation did it, or a platform
+ * actor through `HostAdmin`. Two members rather than a principal with a flag, because an
+ * `act` capability's authority is re-checked against its minter on every use and only a
+ * principal CAN be re-checked — a platform actor holds no tuples.
+ */
+export declare const capabilityAuthor: z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">, z.ZodObject<{
+    platform: z.core.$ZodBranded<z.ZodString, "PlatformActorId", "out">;
+}, z.core.$strip>]>;
+export type CapabilityAuthor = z.infer<typeof capabilityAuthor>;
+/**
+ * A capability as the directory holds it — what `ctx.capabilities.list` returns. Carries
+ * neither the secret nor its hash: the one is never stored, and the other is nothing a
+ * caller has a use for.
+ */
+export declare const capabilityRecord: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.core.$ZodBranded<z.ZodString, "CapabilityId", "out">;
+    label: z.ZodNullable<z.ZodString>;
+    mintedBy: z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">, z.ZodObject<{
+        platform: z.core.$ZodBranded<z.ZodString, "PlatformActorId", "out">;
+    }, z.core.$strip>]>;
+    mintedAt: z.core.$ZodBranded<z.ZodString, "Instant", "out">;
+    expiresAt: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "Instant", "out">>;
+    maxUses: z.ZodNullable<z.ZodNumber>;
+    uses: z.ZodNumber;
+    lastUsedAt: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "Instant", "out">>;
+    revokedAt: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "Instant", "out">>;
+    revokedBy: z.ZodNullable<z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">, z.ZodObject<{
+        platform: z.core.$ZodBranded<z.ZodString, "PlatformActorId", "out">;
+    }, z.core.$strip>]>>;
+    mode: z.ZodLiteral<"act">;
+    entity: z.ZodObject<{
+        entityType: z.ZodString;
+        entityId: z.ZodString;
+    }, z.core.$strip>;
+    permissions: z.ZodArray<z.core.$ZodBranded<z.ZodString, "PermissionKey", "out">>;
+    operations: z.ZodNullable<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.core.$ZodBranded<z.ZodString, "CapabilityId", "out">;
+    label: z.ZodNullable<z.ZodString>;
+    mintedBy: z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">, z.ZodObject<{
+        platform: z.core.$ZodBranded<z.ZodString, "PlatformActorId", "out">;
+    }, z.core.$strip>]>;
+    mintedAt: z.core.$ZodBranded<z.ZodString, "Instant", "out">;
+    expiresAt: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "Instant", "out">>;
+    maxUses: z.ZodNullable<z.ZodNumber>;
+    uses: z.ZodNumber;
+    lastUsedAt: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "Instant", "out">>;
+    revokedAt: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "Instant", "out">>;
+    revokedBy: z.ZodNullable<z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">, z.ZodObject<{
+        platform: z.core.$ZodBranded<z.ZodString, "PlatformActorId", "out">;
+    }, z.core.$strip>]>>;
+    mode: z.ZodLiteral<"become">;
+    principal: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+}, z.core.$strip>], "mode">;
+export type CapabilityRecord = z.infer<typeof capabilityRecord>;
+/**
+ * What a mint hands back — the ONLY time the secret exists outside the caller's hands.
+ * The kernel keeps its hash; a vertical builds the link from it and returns it once.
+ */
+export declare const mintedCapability: z.ZodObject<{
+    id: z.core.$ZodBranded<z.ZodString, "CapabilityId", "out">;
+    secret: z.ZodString;
+    expiresAt: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "Instant", "out">>;
+}, z.core.$strip>;
+export type MintedCapability = z.infer<typeof mintedCapability>;
+/**
+ * What an exchange yields: a session to act as the capability (`act`), or the principal
+ * the holder becomes (`become`). A refused exchange — an unknown, expired, revoked or
+ * used-up secret — is `null`, one answer for all four, so a probe learns nothing.
+ */
+export declare const capabilityExchange: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"session">;
+    capabilityId: z.core.$ZodBranded<z.ZodString, "CapabilityId", "out">;
+    sessionToken: z.ZodString;
+    expiresAt: z.core.$ZodBranded<z.ZodString, "Instant", "out">;
+    entity: z.ZodObject<{
+        entityType: z.ZodString;
+        entityId: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"principal">;
+    capabilityId: z.core.$ZodBranded<z.ZodString, "CapabilityId", "out">;
+    principal: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+}, z.core.$strip>], "kind">;
+export type CapabilityExchange = z.infer<typeof capabilityExchange>;
+/** What narrows `ctx.capabilities.list`. Live capabilities only unless `includeRevoked`. */
+export declare const capabilityFilter: z.ZodObject<{
+    entity: z.ZodOptional<z.ZodObject<{
+        entityType: z.ZodString;
+        entityId: z.ZodString;
+    }, z.core.$strip>>;
+    includeRevoked: z.ZodOptional<z.ZodBoolean>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type CapabilityFilter = z.infer<typeof capabilityFilter>;
+/** A module minted an `act` capability. Entity: the shared entity; actor: the minter. */
+export declare const CAPABILITY_MINTED = "capability.minted";
+/** A module revoked one. Entity: the shared entity; actor: the revoker. */
+export declare const CAPABILITY_REVOKED = "capability.revoked";
+/**
+ * A secret was exchanged — one counted use. Entity: the shared entity for `act`, the
+ * capability itself (`capability:<id>`) for `become`; actor: `{ capability }`.
+ */
+export declare const CAPABILITY_EXERCISED = "capability.exercised";
+export declare const capabilityMintedPayload: z.ZodObject<{
+    capabilityId: z.core.$ZodBranded<z.ZodString, "CapabilityId", "out">;
+    entity: z.ZodObject<{
+        entityType: z.ZodString;
+        entityId: z.ZodString;
+    }, z.core.$strip>;
+    permissions: z.ZodArray<z.core.$ZodBranded<z.ZodString, "PermissionKey", "out">>;
+    operations: z.ZodNullable<z.ZodArray<z.ZodString>>;
+    expiresAt: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "Instant", "out">>;
+    maxUses: z.ZodNullable<z.ZodNumber>;
+    label: z.ZodNullable<z.ZodString>;
+    mintedBy: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+}, z.core.$strip>;
+export type CapabilityMintedPayload = z.infer<typeof capabilityMintedPayload>;
+export declare const capabilityRevokedPayload: z.ZodObject<{
+    capabilityId: z.core.$ZodBranded<z.ZodString, "CapabilityId", "out">;
+    entity: z.ZodObject<{
+        entityType: z.ZodString;
+        entityId: z.ZodString;
+    }, z.core.$strip>;
+    revokedBy: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+}, z.core.$strip>;
+export type CapabilityRevokedPayload = z.infer<typeof capabilityRevokedPayload>;
+export declare const capabilityExercisedPayload: z.ZodObject<{
+    capabilityId: z.core.$ZodBranded<z.ZodString, "CapabilityId", "out">;
+    mode: z.ZodEnum<{
+        act: "act";
+        become: "become";
+    }>;
+    uses: z.ZodNumber;
+    maxUses: z.ZodNullable<z.ZodNumber>;
+    sessionExpiresAt: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "Instant", "out">>;
+    principal: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">>;
+}, z.core.$strip>;
+export type CapabilityExercisedPayload = z.infer<typeof capabilityExercisedPayload>;
+//# sourceMappingURL=capability.d.ts.map

package/dist/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,6FAA6F;AAC7F,eAAO,MAAM,wBAAwB,WAAW,CAAC;AACjD,kEAAkE;AAClE,eAAO,MAAM,yBAAyB,WAAW,CAAC;AAClD,4FAA4F;AAC5F,eAAO,MAAM,yBAAyB,QAAmB,CAAC;AAC1D,gFAAgF;AAChF,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAC7C,+DAA+D;AAC/D,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,gGAAgG;AAChG,eAAO,MAAM,eAAe,aAAoC,CAAC;AAEjE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB;;;;;;;iBAI9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;iBAI9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB;;;;;iBAKhC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;mBAAkE,CAAC;AAChG,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAkBhE;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAc3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,gBAAgB;;;;iBAI3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;2BAa7B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,4FAA4F;AAC5F,eAAO,MAAM,gBAAgB;;;;;;;iBAI3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAShE,yFAAyF;AACzF,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AACrD,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AACvD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D,eAAO,MAAM,uBAAuB;;;;;;;;;;;;iBASlC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE9E,eAAO,MAAM,wBAAwB;;;;;;;iBAInC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF,eAAO,MAAM,0BAA0B;;;;;;;;;;iBAUrC,CAAC;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC"}

package/dist/capability.js

@@ -0,0 +1,210 @@
+import { z } from 'zod';
+import { entityRef } from './events.js';
+import { capabilityId, instant, permissionKey, platformActorId, principalId } from './ids.js';
+/**
+ * Capabilities (#1672) — authority carried by a SECRET rather than held by a principal.
+ *
+ * The permission checker reasons about principals, and a link share is authority held by
+ * whoever has the URL: nobody the checker knows. #97 solved the neighbouring case for
+ * connectors by letting the connection BE an actor; this does the same for a secret. A
+ * capability is a directory row, the row names what it may do, and the holder of its
+ * secret acts as `{ capability: <id> }` — resolved by the checker, recorded on the event,
+ * refused into the denial log, like any other actor.
+ *
+ * It is a building block rather than a link-share feature. The repo carried three
+ * hand-built "authority carried by a secret" mechanisms (owner claim links, member
+ * invites, the dashboard's signed tokens), each with its own table and a code path outside
+ * the checker, none of them on the spine as authority. So the shape here has what those
+ * need even where a link share does not: a use limit beside the expiry, and a `become`
+ * mode for "exercising this binds that principal".
+ *
+ * **Directory-backed, never self-contained.** The checker reads the row on every check, so
+ * revoking one is the next read, and every exchange is a counted, recorded use. Only the
+ * secret's SHA-256 is ever stored; the secret itself leaves the kernel once, in the mint's
+ * return value.
+ *
+ * **A use is an exchange, not an invocation.** The secret is presented once, traded for a
+ * session cookie (so it does not live in history or `Referer`), and the session then acts
+ * until the capability expires or is revoked. A read-only share makes dozens of calls per
+ * page load, and a single-use invite would otherwise be spent by its own redemption — so
+ * `maxUses` bounds how many browsers may hold a capability, not how many reads they make.
+ */
+/** What every minted secret starts with — so a secret scanner can recognise a leaked one. */
+export const CAPABILITY_SECRET_PREFIX = 'sbcap_';
+/** What every session token an exchange hands out starts with. */
+export const CAPABILITY_SESSION_PREFIX = 'sbses_';
+/** How long a session outlives its exchange, at most — never past the capability itself. */
+export const CAPABILITY_SESSION_TTL_MS = 24 * 60 * 60_000;
+/** The most keys one capability may carry. A link that needs more is a role. */
+export const CAPABILITY_PERMISSIONS_MAX = 16;
+/** The most operations one capability's allowlist may name. */
+export const CAPABILITY_OPERATIONS_MAX = 32;
+/** An optional operator-facing name for a capability ("client review link"). Never a secret. */
+export const capabilityLabel = z.string().trim().min(1).max(200);
+/**
+ * (Not `capabilityGrant` — that older name in `permission.ts` is an entity-narrowed grant
+ * to a PRINCIPAL, and predates this module.)
+ *
+ * What an `act` capability may do: ONE entity and everything beneath it through declared
+ * parent edges, specific keys on that subtree, and optionally an allowlist of operations.
+ *
+ * The keys are the authority — each is checked against the entity exactly as an
+ * entity-narrowed grant would be, which is how grants already travel. `operations`
+ * narrows on top of them and never widens: an operation outside the list is refused at
+ * the door before its handler runs, however much the keys would have allowed. A
+ * capability never holds node-level authority, so an operation whose only check is a
+ * node-level one refuses it.
+ */
+export const capabilityAuthority = z.object({
+    entity: entityRef,
+    permissions: z.array(permissionKey).min(1).max(CAPABILITY_PERMISSIONS_MAX),
+    operations: z.array(z.string().min(1)).min(1).max(CAPABILITY_OPERATIONS_MAX).optional(),
+});
+/**
+ * What a MODULE may mint (`ctx.capabilities.mint`) — always an `act` capability.
+ *
+ * `expiresAt` absent means no expiry; `maxUses` absent means unlimited exchanges. Both are
+ * a vertical's call: "anyone with the link" is how most sharing works, and a link share
+ * that must die on Friday says so. Neither widens authority — the minter's own is
+ * re-checked on every use.
+ */
+export const capabilityMintInput = capabilityAuthority.extend({
+    expiresAt: instant.optional(),
+    maxUses: z.number().int().positive().optional(),
+    label: capabilityLabel.optional(),
+});
+/**
+ * What the PLATFORM may mint (`HostAdmin.mintCapability`) — a `become` capability:
+ * exchanging it yields a principal instead of a session, the shape an owner claim link and
+ * a member invite are ("whoever opens this becomes that seat").
+ *
+ * Platform-only in this first cut, deliberately. `become` is impersonation by another name
+ * — the holder acquires everything the principal holds — so the bound on who may mint one
+ * from module code is designed with the invite and claim migrations, not guessed here.
+ * Expiry and a use limit are REQUIRED for the same reason: an unbounded `become` is a
+ * standing credential for a person.
+ */
+export const becomeCapabilityInput = z.object({
+    principal: principalId,
+    expiresAt: instant,
+    maxUses: z.number().int().positive(),
+    label: capabilityLabel.optional(),
+});
+/**
+ * Who minted or revoked a capability: the principal whose operation did it, or a platform
+ * actor through `HostAdmin`. Two members rather than a principal with a flag, because an
+ * `act` capability's authority is re-checked against its minter on every use and only a
+ * principal CAN be re-checked — a platform actor holds no tuples.
+ */
+export const capabilityAuthor = z.union([principalId, z.object({ platform: platformActorId })]);
+const capabilityRecordCommon = {
+    id: capabilityId,
+    label: capabilityLabel.nullable(),
+    mintedBy: capabilityAuthor,
+    mintedAt: instant,
+    /** Null = never expires. */
+    expiresAt: instant.nullable(),
+    /** Null = unlimited exchanges. */
+    maxUses: z.number().int().positive().nullable(),
+    /** Exchanges so far. Never above `maxUses`. */
+    uses: z.number().int().nonnegative(),
+    lastUsedAt: instant.nullable(),
+    revokedAt: instant.nullable(),
+    revokedBy: capabilityAuthor.nullable(),
+};
+/**
+ * A capability as the directory holds it — what `ctx.capabilities.list` returns. Carries
+ * neither the secret nor its hash: the one is never stored, and the other is nothing a
+ * caller has a use for.
+ */
+export const capabilityRecord = z.discriminatedUnion('mode', [
+    z.object({
+        mode: z.literal('act'),
+        ...capabilityRecordCommon,
+        entity: entityRef,
+        permissions: z.array(permissionKey).min(1),
+        /** Null = any operation the keys allow. */
+        operations: z.array(z.string().min(1)).nullable(),
+    }),
+    z.object({
+        mode: z.literal('become'),
+        ...capabilityRecordCommon,
+        principal: principalId,
+    }),
+]);
+/**
+ * What a mint hands back — the ONLY time the secret exists outside the caller's hands.
+ * The kernel keeps its hash; a vertical builds the link from it and returns it once.
+ */
+export const mintedCapability = z.object({
+    id: capabilityId,
+    secret: z.string().startsWith(CAPABILITY_SECRET_PREFIX),
+    expiresAt: instant.nullable(),
+});
+/**
+ * What an exchange yields: a session to act as the capability (`act`), or the principal
+ * the holder becomes (`become`). A refused exchange — an unknown, expired, revoked or
+ * used-up secret — is `null`, one answer for all four, so a probe learns nothing.
+ */
+export const capabilityExchange = z.discriminatedUnion('kind', [
+    z.object({
+        kind: z.literal('session'),
+        capabilityId,
+        sessionToken: z.string().startsWith(CAPABILITY_SESSION_PREFIX),
+        expiresAt: instant,
+        entity: entityRef,
+    }),
+    z.object({
+        kind: z.literal('principal'),
+        capabilityId,
+        principal: principalId,
+    }),
+]);
+/** What narrows `ctx.capabilities.list`. Live capabilities only unless `includeRevoked`. */
+export const capabilityFilter = z.object({
+    entity: entityRef.optional(),
+    includeRevoked: z.boolean().optional(),
+    limit: z.number().int().min(1).max(200).optional(),
+});
+// ---------------------------------------------------------------------------
+// The spine events the kernel emits about capabilities — kernel-authored, like
+// `attachment.added`, so module code can neither forge nor suppress them. Fat, per
+// the event rule: a consumer never has to read the directory to know what happened.
+// Never the secret, never its hash.
+// ---------------------------------------------------------------------------
+/** A module minted an `act` capability. Entity: the shared entity; actor: the minter. */
+export const CAPABILITY_MINTED = 'capability.minted';
+/** A module revoked one. Entity: the shared entity; actor: the revoker. */
+export const CAPABILITY_REVOKED = 'capability.revoked';
+/**
+ * A secret was exchanged — one counted use. Entity: the shared entity for `act`, the
+ * capability itself (`capability:<id>`) for `become`; actor: `{ capability }`.
+ */
+export const CAPABILITY_EXERCISED = 'capability.exercised';
+export const capabilityMintedPayload = z.object({
+    capabilityId,
+    entity: entityRef,
+    permissions: z.array(permissionKey).min(1),
+    operations: z.array(z.string().min(1)).nullable(),
+    expiresAt: instant.nullable(),
+    maxUses: z.number().int().positive().nullable(),
+    label: capabilityLabel.nullable(),
+    mintedBy: principalId,
+});
+export const capabilityRevokedPayload = z.object({
+    capabilityId,
+    entity: entityRef,
+    revokedBy: principalId,
+});
+export const capabilityExercisedPayload = z.object({
+    capabilityId,
+    mode: z.enum(['act', 'become']),
+    /** The count AFTER this exchange. */
+    uses: z.number().int().positive(),
+    maxUses: z.number().int().positive().nullable(),
+    /** `act`: when the session this exchange handed out stops working. Null for `become`. */
+    sessionExpiresAt: instant.nullable(),
+    /** `become`: the principal the holder became. Null for `act`. */
+    principal: principalId.nullable(),
+});
+//# sourceMappingURL=capability.js.map

package/dist/capability.js.map

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