@fuzdev/fuz_app 0.30.0 → 0.31.0

package/dist/auth/permit_offer_action_specs.d.ts

@@ -0,0 +1,364 @@
+/**
+ * Permit offer RPC action specs — declarative contract for the
+ * consentful-permits surface (offer lifecycle + admin revoke).
+ *
+ * Import this module for the specs, Input/Output schemas, `ERROR_OFFER_*`
+ * reason constants, and the `all_permit_offer_action_specs` registry.
+ * Handlers live in `./permit_offer_actions.js`.
+ *
+ * Authorization enforcement: offer-lifecycle specs declare
+ * `auth: 'authenticated'` and rely on `query_*` IDOR guards or in-handler
+ * policy checks (e.g. `permit_offer_list`/`_history` elevate to admin only
+ * when inspecting another account — an input-dependent check that can't be
+ * expressed at the spec level). `permit_revoke` declares
+ * `auth: {role: 'admin'}` — the RPC dispatcher's per-spec `check_action_auth`
+ * gates it before the handler runs even though the endpoint hosts non-admin
+ * methods alongside.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import type { RequestResponseActionSpec } from '../actions/action_spec.js';
+/** Error reason — caller tried to offer themselves a permit. */
+export declare const ERROR_OFFER_SELF_TARGET: "offer_self_target";
+/** Error reason — offer is declined, retracted, or superseded. */
+export declare const ERROR_OFFER_TERMINAL: "offer_terminal";
+/** Error reason — offer's `expires_at` has passed. */
+export declare const ERROR_OFFER_EXPIRED: "offer_expired";
+/** Error reason — offer does not exist or belongs to a different recipient (404-over-403 IDOR mask). */
+export declare const ERROR_OFFER_NOT_FOUND: "offer_not_found";
+/** Error reason — the offered role is not `web_grantable` (nobody may offer it via this surface). */
+export declare const ERROR_OFFER_ROLE_NOT_GRANTABLE: "offer_role_not_grantable";
+/** Error reason — caller is not authorized to offer this role (default policy: caller lacks the role; consumer `authorize` callback may add further policy). */
+export declare const ERROR_OFFER_NOT_AUTHORIZED: "offer_not_authorized";
+/** Input for `permit_offer_create`. */
+export declare const PermitOfferCreateInput: z.ZodObject<{
+    to_account_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    role: z.ZodString;
+    scope_id: z.ZodOptional<z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>>;
+    message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type PermitOfferCreateInput = z.infer<typeof PermitOfferCreateInput>;
+/** Input for `permit_offer_accept`. */
+export declare const PermitOfferAcceptInput: z.ZodObject<{
+    offer_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+}, z.core.$strict>;
+export type PermitOfferAcceptInput = z.infer<typeof PermitOfferAcceptInput>;
+/** Input for `permit_offer_decline`. */
+export declare const PermitOfferDeclineInput: z.ZodObject<{
+    offer_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type PermitOfferDeclineInput = z.infer<typeof PermitOfferDeclineInput>;
+/** Input for `permit_offer_retract`. */
+export declare const PermitOfferRetractInput: z.ZodObject<{
+    offer_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+}, z.core.$strict>;
+export type PermitOfferRetractInput = z.infer<typeof PermitOfferRetractInput>;
+/** Input for `permit_offer_list`. `account_id` is admin-only (inspect another account's inbox). */
+export declare const PermitOfferListInput: z.ZodObject<{
+    account_id: z.ZodOptional<z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>>;
+}, z.core.$strict>;
+export type PermitOfferListInput = z.infer<typeof PermitOfferListInput>;
+/**
+ * Input for `permit_revoke`. Admin-only mutation that revokes an active
+ * permit on a target actor. `actor_id` is the natural key — permits are
+ * actor-scoped, and the admin UI reads `row.actor.id` straight from the
+ * listing. Deriving `actor_id` from `account_id` would collapse under
+ * multi-actor accounts.
+ */
+export declare const PermitRevokeInput: z.ZodObject<{
+    actor_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    permit_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type PermitRevokeInput = z.infer<typeof PermitRevokeInput>;
+/**
+ * Input for `permit_offer_history`. Returns every offer involving the account
+ * in either direction (recipient or grantor), including terminal rows, newest
+ * first. `account_id` is admin-only.
+ */
+export declare const PermitOfferHistoryInput: z.ZodObject<{
+    account_id: z.ZodOptional<z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>>;
+    limit: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    offset: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strict>;
+export type PermitOfferHistoryInput = z.infer<typeof PermitOfferHistoryInput>;
+/** Output for `permit_offer_create`. */
+export declare const PermitOfferCreateOutput: z.ZodObject<{
+    offer: z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        from_actor_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        to_account_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        role: z.ZodString;
+        scope_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+        message: z.ZodNullable<z.ZodString>;
+        created_at: z.ZodString;
+        expires_at: z.ZodString;
+        accepted_at: z.ZodNullable<z.ZodString>;
+        declined_at: z.ZodNullable<z.ZodString>;
+        decline_reason: z.ZodNullable<z.ZodString>;
+        retracted_at: z.ZodNullable<z.ZodString>;
+        superseded_at: z.ZodNullable<z.ZodString>;
+        resulting_permit_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type PermitOfferCreateOutput = z.infer<typeof PermitOfferCreateOutput>;
+/** Output for `permit_offer_accept`. */
+export declare const PermitOfferAcceptOutput: z.ZodObject<{
+    permit_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    offer: z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        from_actor_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        to_account_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        role: z.ZodString;
+        scope_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+        message: z.ZodNullable<z.ZodString>;
+        created_at: z.ZodString;
+        expires_at: z.ZodString;
+        accepted_at: z.ZodNullable<z.ZodString>;
+        declined_at: z.ZodNullable<z.ZodString>;
+        decline_reason: z.ZodNullable<z.ZodString>;
+        retracted_at: z.ZodNullable<z.ZodString>;
+        superseded_at: z.ZodNullable<z.ZodString>;
+        resulting_permit_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    }, z.core.$strict>;
+    superseded_offer_ids: z.ZodArray<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+}, z.core.$strict>;
+export type PermitOfferAcceptOutput = z.infer<typeof PermitOfferAcceptOutput>;
+/** Output for `permit_offer_decline` / `permit_offer_retract`. */
+export declare const PermitOfferOkOutput: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+}, z.core.$strict>;
+export type PermitOfferOkOutput = z.infer<typeof PermitOfferOkOutput>;
+/** Output for `permit_offer_list`. */
+export declare const PermitOfferListOutput: z.ZodObject<{
+    offers: z.ZodArray<z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        from_actor_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        to_account_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        role: z.ZodString;
+        scope_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+        message: z.ZodNullable<z.ZodString>;
+        created_at: z.ZodString;
+        expires_at: z.ZodString;
+        accepted_at: z.ZodNullable<z.ZodString>;
+        declined_at: z.ZodNullable<z.ZodString>;
+        decline_reason: z.ZodNullable<z.ZodString>;
+        retracted_at: z.ZodNullable<z.ZodString>;
+        superseded_at: z.ZodNullable<z.ZodString>;
+        resulting_permit_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PermitOfferListOutput = z.infer<typeof PermitOfferListOutput>;
+/** Output for `permit_offer_history`. */
+export declare const PermitOfferHistoryOutput: z.ZodObject<{
+    offers: z.ZodArray<z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        from_actor_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        to_account_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        role: z.ZodString;
+        scope_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+        message: z.ZodNullable<z.ZodString>;
+        created_at: z.ZodString;
+        expires_at: z.ZodString;
+        accepted_at: z.ZodNullable<z.ZodString>;
+        declined_at: z.ZodNullable<z.ZodString>;
+        decline_reason: z.ZodNullable<z.ZodString>;
+        retracted_at: z.ZodNullable<z.ZodString>;
+        superseded_at: z.ZodNullable<z.ZodString>;
+        resulting_permit_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PermitOfferHistoryOutput = z.infer<typeof PermitOfferHistoryOutput>;
+/** Output for `permit_revoke`. */
+export declare const PermitRevokeOutput: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    revoked: z.ZodLiteral<true>;
+}, z.core.$strict>;
+export type PermitRevokeOutput = z.infer<typeof PermitRevokeOutput>;
+export declare const permit_offer_create_action_spec: {
+    method: string;
+    kind: "request_response";
+    initiator: "frontend";
+    auth: "authenticated";
+    side_effects: true;
+    input: z.ZodObject<{
+        to_account_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        role: z.ZodString;
+        scope_id: z.ZodOptional<z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>>;
+        message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>;
+    output: z.ZodObject<{
+        offer: z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            from_actor_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            to_account_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            role: z.ZodString;
+            scope_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+            message: z.ZodNullable<z.ZodString>;
+            created_at: z.ZodString;
+            expires_at: z.ZodString;
+            accepted_at: z.ZodNullable<z.ZodString>;
+            declined_at: z.ZodNullable<z.ZodString>;
+            decline_reason: z.ZodNullable<z.ZodString>;
+            retracted_at: z.ZodNullable<z.ZodString>;
+            superseded_at: z.ZodNullable<z.ZodString>;
+            resulting_permit_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    async: true;
+    description: string;
+};
+export declare const permit_offer_accept_action_spec: {
+    method: string;
+    kind: "request_response";
+    initiator: "frontend";
+    auth: "authenticated";
+    side_effects: true;
+    input: z.ZodObject<{
+        offer_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    }, z.core.$strict>;
+    output: z.ZodObject<{
+        permit_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        offer: z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            from_actor_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            to_account_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            role: z.ZodString;
+            scope_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+            message: z.ZodNullable<z.ZodString>;
+            created_at: z.ZodString;
+            expires_at: z.ZodString;
+            accepted_at: z.ZodNullable<z.ZodString>;
+            declined_at: z.ZodNullable<z.ZodString>;
+            decline_reason: z.ZodNullable<z.ZodString>;
+            retracted_at: z.ZodNullable<z.ZodString>;
+            superseded_at: z.ZodNullable<z.ZodString>;
+            resulting_permit_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+        }, z.core.$strict>;
+        superseded_offer_ids: z.ZodArray<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    }, z.core.$strict>;
+    async: true;
+    description: string;
+};
+export declare const permit_offer_decline_action_spec: {
+    method: string;
+    kind: "request_response";
+    initiator: "frontend";
+    auth: "authenticated";
+    side_effects: true;
+    input: z.ZodObject<{
+        offer_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>;
+    output: z.ZodObject<{
+        ok: z.ZodLiteral<true>;
+    }, z.core.$strict>;
+    async: true;
+    description: string;
+};
+export declare const permit_offer_retract_action_spec: {
+    method: string;
+    kind: "request_response";
+    initiator: "frontend";
+    auth: "authenticated";
+    side_effects: true;
+    input: z.ZodObject<{
+        offer_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    }, z.core.$strict>;
+    output: z.ZodObject<{
+        ok: z.ZodLiteral<true>;
+    }, z.core.$strict>;
+    async: true;
+    description: string;
+};
+export declare const permit_offer_list_action_spec: {
+    method: string;
+    kind: "request_response";
+    initiator: "frontend";
+    auth: "authenticated";
+    side_effects: false;
+    input: z.ZodObject<{
+        account_id: z.ZodOptional<z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>>;
+    }, z.core.$strict>;
+    output: z.ZodObject<{
+        offers: z.ZodArray<z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            from_actor_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            to_account_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            role: z.ZodString;
+            scope_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+            message: z.ZodNullable<z.ZodString>;
+            created_at: z.ZodString;
+            expires_at: z.ZodString;
+            accepted_at: z.ZodNullable<z.ZodString>;
+            declined_at: z.ZodNullable<z.ZodString>;
+            decline_reason: z.ZodNullable<z.ZodString>;
+            retracted_at: z.ZodNullable<z.ZodString>;
+            superseded_at: z.ZodNullable<z.ZodString>;
+            resulting_permit_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    async: true;
+    description: string;
+};
+export declare const permit_offer_history_action_spec: {
+    method: string;
+    kind: "request_response";
+    initiator: "frontend";
+    auth: "authenticated";
+    side_effects: false;
+    input: z.ZodObject<{
+        account_id: z.ZodOptional<z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>>;
+        limit: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        offset: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strict>;
+    output: z.ZodObject<{
+        offers: z.ZodArray<z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            from_actor_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            to_account_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            role: z.ZodString;
+            scope_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+            message: z.ZodNullable<z.ZodString>;
+            created_at: z.ZodString;
+            expires_at: z.ZodString;
+            accepted_at: z.ZodNullable<z.ZodString>;
+            declined_at: z.ZodNullable<z.ZodString>;
+            decline_reason: z.ZodNullable<z.ZodString>;
+            retracted_at: z.ZodNullable<z.ZodString>;
+            superseded_at: z.ZodNullable<z.ZodString>;
+            resulting_permit_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    async: true;
+    description: string;
+};
+export declare const permit_revoke_action_spec: {
+    method: string;
+    kind: "request_response";
+    initiator: "frontend";
+    auth: {
+        role: string;
+    };
+    side_effects: true;
+    input: z.ZodObject<{
+        actor_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        permit_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>;
+    output: z.ZodObject<{
+        ok: z.ZodLiteral<true>;
+        revoked: z.ZodLiteral<true>;
+    }, z.core.$strict>;
+    async: true;
+    description: string;
+};
+/**
+ * All permit-offer action specs — a codegen-ready registry. Consumers spread
+ * this into their own action-spec array to include offer lifecycle + revoke
+ * methods in a typed client surface.
+ */
+export declare const all_permit_offer_action_specs: Array<RequestResponseActionSpec>;
+//# sourceMappingURL=permit_offer_action_specs.d.ts.map

package/dist/auth/permit_offer_action_specs.d.ts.map

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

package/dist/auth/permit_offer_action_specs.js

@@ -0,0 +1,216 @@
+/**
+ * Permit offer RPC action specs — declarative contract for the
+ * consentful-permits surface (offer lifecycle + admin revoke).
+ *
+ * Import this module for the specs, Input/Output schemas, `ERROR_OFFER_*`
+ * reason constants, and the `all_permit_offer_action_specs` registry.
+ * Handlers live in `./permit_offer_actions.js`.
+ *
+ * Authorization enforcement: offer-lifecycle specs declare
+ * `auth: 'authenticated'` and rely on `query_*` IDOR guards or in-handler
+ * policy checks (e.g. `permit_offer_list`/`_history` elevate to admin only
+ * when inspecting another account — an input-dependent check that can't be
+ * expressed at the spec level). `permit_revoke` declares
+ * `auth: {role: 'admin'}` — the RPC dispatcher's per-spec `check_action_auth`
+ * gates it before the handler runs even though the endpoint hosts non-admin
+ * methods alongside.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { Uuid } from '../uuid.js';
+import { RoleName } from './role_schema.js';
+import { PERMIT_OFFER_MESSAGE_LENGTH_MAX, PermitOfferJson } from './permit_offer_schema.js';
+import { PERMIT_REVOKED_REASON_LENGTH_MAX } from './account_schema.js';
+/** Error reason — caller tried to offer themselves a permit. */
+export const ERROR_OFFER_SELF_TARGET = 'offer_self_target';
+/** Error reason — offer is declined, retracted, or superseded. */
+export const ERROR_OFFER_TERMINAL = 'offer_terminal';
+/** Error reason — offer's `expires_at` has passed. */
+export const ERROR_OFFER_EXPIRED = 'offer_expired';
+/** Error reason — offer does not exist or belongs to a different recipient (404-over-403 IDOR mask). */
+export const ERROR_OFFER_NOT_FOUND = 'offer_not_found';
+/** Error reason — the offered role is not `web_grantable` (nobody may offer it via this surface). */
+export const ERROR_OFFER_ROLE_NOT_GRANTABLE = 'offer_role_not_grantable';
+/** Error reason — caller is not authorized to offer this role (default policy: caller lacks the role; consumer `authorize` callback may add further policy). */
+export const ERROR_OFFER_NOT_AUTHORIZED = 'offer_not_authorized';
+// -- Input/output schemas ---------------------------------------------------
+/** Input for `permit_offer_create`. */
+export const PermitOfferCreateInput = z.strictObject({
+    to_account_id: Uuid.meta({ description: 'Account id of the recipient.' }),
+    role: RoleName.meta({ description: 'Role being offered.' }),
+    scope_id: Uuid.nullish().meta({
+        description: 'Scope id for resource-scoped grants (e.g. classroom id). `null` for global.',
+    }),
+    message: z
+        .string()
+        .max(PERMIT_OFFER_MESSAGE_LENGTH_MAX)
+        .nullish()
+        .meta({ description: 'Optional free-form note from the grantor.' }),
+});
+/** Input for `permit_offer_accept`. */
+export const PermitOfferAcceptInput = z.strictObject({
+    offer_id: Uuid.meta({ description: 'The offer to accept.' }),
+});
+/** Input for `permit_offer_decline`. */
+export const PermitOfferDeclineInput = z.strictObject({
+    offer_id: Uuid.meta({ description: 'The offer to decline.' }),
+    reason: z
+        .string()
+        .max(PERMIT_OFFER_MESSAGE_LENGTH_MAX)
+        .nullish()
+        .meta({ description: 'Optional free-form reason given on decline.' }),
+});
+/** Input for `permit_offer_retract`. */
+export const PermitOfferRetractInput = z.strictObject({
+    offer_id: Uuid.meta({ description: 'The offer to retract.' }),
+});
+/** Input for `permit_offer_list`. `account_id` is admin-only (inspect another account's inbox). */
+export const PermitOfferListInput = z.strictObject({
+    account_id: Uuid.nullish().meta({
+        description: 'Admin-only — list offers for another account. Defaults to the caller.',
+    }),
+});
+/**
+ * Input for `permit_revoke`. Admin-only mutation that revokes an active
+ * permit on a target actor. `actor_id` is the natural key — permits are
+ * actor-scoped, and the admin UI reads `row.actor.id` straight from the
+ * listing. Deriving `actor_id` from `account_id` would collapse under
+ * multi-actor accounts.
+ */
+export const PermitRevokeInput = z.strictObject({
+    actor_id: Uuid.meta({ description: 'Actor whose permit to revoke.' }),
+    permit_id: Uuid.meta({ description: 'The permit to revoke.' }),
+    reason: z.string().max(PERMIT_REVOKED_REASON_LENGTH_MAX).nullish().meta({
+        description: 'Optional free-form reason; stamped on `permit.revoked_reason` and surfaced on the revokee WS notification.',
+    }),
+});
+/**
+ * Input for `permit_offer_history`. Returns every offer involving the account
+ * in either direction (recipient or grantor), including terminal rows, newest
+ * first. `account_id` is admin-only.
+ */
+export const PermitOfferHistoryInput = z.strictObject({
+    account_id: Uuid.nullish().meta({
+        description: 'Admin-only — history for another account. Defaults to the caller.',
+    }),
+    limit: z.number().int().min(1).max(500).nullish().meta({
+        description: 'Max rows to return (default 100).',
+    }),
+    offset: z.number().int().min(0).nullish().meta({
+        description: 'Pagination offset (default 0).',
+    }),
+});
+/** Output for `permit_offer_create`. */
+export const PermitOfferCreateOutput = z.strictObject({
+    offer: PermitOfferJson,
+});
+/** Output for `permit_offer_accept`. */
+export const PermitOfferAcceptOutput = z.strictObject({
+    permit_id: Uuid,
+    offer: PermitOfferJson,
+    superseded_offer_ids: z.array(Uuid),
+});
+/** Output for `permit_offer_decline` / `permit_offer_retract`. */
+export const PermitOfferOkOutput = z.strictObject({ ok: z.literal(true) });
+/** Output for `permit_offer_list`. */
+export const PermitOfferListOutput = z.strictObject({ offers: z.array(PermitOfferJson) });
+/** Output for `permit_offer_history`. */
+export const PermitOfferHistoryOutput = z.strictObject({ offers: z.array(PermitOfferJson) });
+/** Output for `permit_revoke`. */
+export const PermitRevokeOutput = z.strictObject({
+    ok: z.literal(true),
+    revoked: z.literal(true),
+});
+// -- Action specs -----------------------------------------------------------
+export const permit_offer_create_action_spec = {
+    method: 'permit_offer_create',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: 'authenticated',
+    side_effects: true,
+    input: PermitOfferCreateInput,
+    output: PermitOfferCreateOutput,
+    async: true,
+    description: 'Offer a permit to another account. Grantor must hold the offered role (or pass a consumer authorize callback); role must be web_grantable.',
+};
+export const permit_offer_accept_action_spec = {
+    method: 'permit_offer_accept',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: 'authenticated',
+    side_effects: true,
+    input: PermitOfferAcceptInput,
+    output: PermitOfferAcceptOutput,
+    async: true,
+    description: 'Accept an offer. Atomically marks the offer accepted, inserts the permit, and supersedes sibling pending offers for the same (account, role, scope).',
+};
+export const permit_offer_decline_action_spec = {
+    method: 'permit_offer_decline',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: 'authenticated',
+    side_effects: true,
+    input: PermitOfferDeclineInput,
+    output: PermitOfferOkOutput,
+    async: true,
+    description: 'Decline an offer. Recipient-only.',
+};
+export const permit_offer_retract_action_spec = {
+    method: 'permit_offer_retract',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: 'authenticated',
+    side_effects: true,
+    input: PermitOfferRetractInput,
+    output: PermitOfferOkOutput,
+    async: true,
+    description: 'Retract an offer. Grantor-only, pre-decision.',
+};
+export const permit_offer_list_action_spec = {
+    method: 'permit_offer_list',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: 'authenticated',
+    side_effects: false,
+    input: PermitOfferListInput,
+    output: PermitOfferListOutput,
+    async: true,
+    description: 'List pending, non-expired offers for the caller. Admins may pass `account_id` to inspect another account.',
+};
+export const permit_offer_history_action_spec = {
+    method: 'permit_offer_history',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: 'authenticated',
+    side_effects: false,
+    input: PermitOfferHistoryInput,
+    output: PermitOfferHistoryOutput,
+    async: true,
+    description: 'List every offer involving the caller (either direction), including terminal rows, newest first. Admins may pass `account_id` to inspect another account.',
+};
+export const permit_revoke_action_spec = {
+    method: 'permit_revoke',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { role: 'admin' },
+    side_effects: true,
+    input: PermitRevokeInput,
+    output: PermitRevokeOutput,
+    async: true,
+    description: 'Revoke an active permit on a target actor. Admin-only. Supersedes any pending offers for the same (account, role, scope). Fires permit_revoke + permit_offer_supersede notifications.',
+};
+/**
+ * All permit-offer action specs — a codegen-ready registry. Consumers spread
+ * this into their own action-spec array to include offer lifecycle + revoke
+ * methods in a typed client surface.
+ */
+export const all_permit_offer_action_specs = [
+    permit_offer_create_action_spec,
+    permit_offer_accept_action_spec,
+    permit_offer_decline_action_spec,
+    permit_offer_retract_action_spec,
+    permit_offer_list_action_spec,
+    permit_offer_history_action_spec,
+    permit_revoke_action_spec,
+];