@fuzdev/fuz_app 0.54.0 → 0.56.0

package/dist/auth/role_grant_offer_action_specs.js

@@ -0,0 +1,262 @@
+/**
+ * Role grant offer RPC action specs — declarative contract for the
+ * consentful-role-grants surface (offer lifecycle + admin revoke).
+ *
+ * Import this module for the specs, Input/Output schemas, `ERROR_ROLE_GRANT_OFFER_*`
+ * reason constants, and the `all_role_grant_offer_action_specs` registry.
+ * Handlers live in `auth/role_grant_offer_actions.ts`.
+ *
+ * Authorization enforcement: offer-lifecycle specs declare account+actor
+ * required (no roles) and rely on `query_*` IDOR guards or in-handler
+ * policy checks (e.g. `role_grant_offer_list`/`_history` elevate to admin only
+ * when inspecting another account — an input-dependent check that can't be
+ * expressed at the spec level). `role_grant_revoke` adds `roles: ['admin']` —
+ * the RPC dispatcher's per-spec post-authorization auth gate
+ * (`check_action_auth_post_authorization`) rejects non-admin callers before
+ * the handler runs even though the endpoint hosts non-admin methods
+ * alongside.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { Uuid } from '@fuzdev/fuz_util/id.js';
+import { ERROR_ROLE_GRANT_NOT_FOUND, ERROR_ROLE_NOT_WEB_GRANTABLE } from '../http/error_schemas.js';
+import { RoleName } from './role_schema.js';
+import { ROLE_GRANT_OFFER_MESSAGE_LENGTH_MAX, RoleGrantOfferJson, } from './role_grant_offer_schema.js';
+import { ROLE_GRANT_REVOKED_REASON_LENGTH_MAX } from './account_schema.js';
+import { ActingActor } from '../http/auth_shape.js';
+/** Error reason — caller tried to offer themselves a role_grant. */
+export const ERROR_ROLE_GRANT_OFFER_SELF_TARGET = 'role_grant_offer_self_target';
+/** Error reason — offer is declined, retracted, or superseded. */
+export const ERROR_ROLE_GRANT_OFFER_TERMINAL = 'role_grant_offer_terminal';
+/** Error reason — offer's `expires_at` has passed. */
+export const ERROR_ROLE_GRANT_OFFER_EXPIRED = 'role_grant_offer_expired';
+/** Error reason — offer does not exist or belongs to a different recipient (404-over-403 IDOR mask). */
+export const ERROR_ROLE_GRANT_OFFER_NOT_FOUND = 'role_grant_offer_not_found';
+/** Error reason — the offered role does not include `'admin'` in its `RoleSpec.grant_paths` (nobody may offer it via this surface). */
+export const ERROR_ROLE_GRANT_OFFER_ROLE_NOT_GRANTABLE = 'role_grant_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_ROLE_GRANT_OFFER_NOT_AUTHORIZED = 'role_grant_offer_not_authorized';
+/** Error reason — actor-targeted offer was accepted by an actor other than `to_actor_id`. */
+export const ERROR_ROLE_GRANT_OFFER_ACTOR_MISMATCH = 'role_grant_offer_actor_mismatch';
+/** Error reason — `role_grant_offer_create` was called with a `to_actor_id` that does not belong to `to_account_id`. */
+export const ERROR_ROLE_GRANT_OFFER_ACTOR_ACCOUNT_MISMATCH = 'role_grant_offer_actor_account_mismatch';
+// -- Input/output schemas ---------------------------------------------------
+/**
+ * Input for `role_grant_offer_create`.
+ *
+ * `to_actor_id` (optional) narrows the offer to a specific actor on the
+ * recipient account. When supplied, `role_grant_offer_accept` will only admit
+ * the named actor — wrong-actor accepts reject with
+ * `role_grant_offer_actor_mismatch`. The audit envelope's `target_actor_id` is
+ * stamped from this column on the create / supersede / expire / retract
+ * events. Omit (or pass null) for the account-grain default — any actor
+ * on `to_account_id` may accept.
+ */
+export const RoleGrantOfferCreateInput = z.strictObject({
+    to_account_id: Uuid.meta({ description: 'Account id of the recipient.' }),
+    to_actor_id: Uuid.nullish().meta({
+        description: 'Optional actor-grain target on the recipient account. When set, only this actor may accept and the audit envelope carries it on offer-shape events. Must belong to `to_account_id`.',
+    }),
+    role: RoleName.meta({ description: 'Role being offered.' }),
+    scope_kind: z.string().nullish().meta({
+        description: 'Machine-readable kind tag for `scope_id` — paired-null with `scope_id` (both null for global, both non-null for scoped). Required iff `scope_id` is set.',
+    }),
+    scope_id: Uuid.nullish().meta({
+        description: 'Scope id for resource-scoped grants (e.g. classroom id). `null` for global.',
+    }),
+    message: z
+        .string()
+        .max(ROLE_GRANT_OFFER_MESSAGE_LENGTH_MAX)
+        .nullish()
+        .meta({ description: 'Optional free-form note from the grantor.' }),
+    acting: ActingActor,
+});
+/** Input for `role_grant_offer_accept`. */
+export const RoleGrantOfferAcceptInput = z.strictObject({
+    offer_id: Uuid.meta({ description: 'The offer to accept.' }),
+    acting: ActingActor,
+});
+/** Input for `role_grant_offer_decline`. */
+export const RoleGrantOfferDeclineInput = z.strictObject({
+    offer_id: Uuid.meta({ description: 'The offer to decline.' }),
+    reason: z
+        .string()
+        .max(ROLE_GRANT_OFFER_MESSAGE_LENGTH_MAX)
+        .nullish()
+        .meta({ description: 'Optional free-form reason given on decline.' }),
+    acting: ActingActor,
+});
+/** Input for `role_grant_offer_retract`. */
+export const RoleGrantOfferRetractInput = z.strictObject({
+    offer_id: Uuid.meta({ description: 'The offer to retract.' }),
+    acting: ActingActor,
+});
+/** Input for `role_grant_offer_list`. `account_id` is admin-only (inspect another account's inbox). */
+export const RoleGrantOfferListInput = z.strictObject({
+    account_id: Uuid.nullish().meta({
+        description: 'Admin-only — list offers for another account. Defaults to the caller.',
+    }),
+    acting: ActingActor,
+});
+/**
+ * Input for `role_grant_revoke`. Admin-only mutation that revokes an active
+ * role_grant on a target actor. `actor_id` is the natural key — role_grants 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 RoleGrantRevokeInput = z.strictObject({
+    actor_id: Uuid.meta({ description: 'Actor whose role_grant to revoke.' }),
+    role_grant_id: Uuid.meta({ description: 'The role_grant to revoke.' }),
+    reason: z.string().max(ROLE_GRANT_REVOKED_REASON_LENGTH_MAX).nullish().meta({
+        description: 'Optional free-form reason; stamped on `role_grant.revoked_reason` and surfaced on the revokee WS notification.',
+    }),
+    acting: ActingActor,
+});
+/**
+ * Input for `role_grant_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 RoleGrantOfferHistoryInput = 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).',
+    }),
+    acting: ActingActor,
+});
+/** Output for `role_grant_offer_create`. */
+export const RoleGrantOfferCreateOutput = z.strictObject({
+    offer: RoleGrantOfferJson,
+});
+/** Output for `role_grant_offer_accept`. */
+export const RoleGrantOfferAcceptOutput = z.strictObject({
+    role_grant_id: Uuid,
+    offer: RoleGrantOfferJson,
+    superseded_offer_ids: z.array(Uuid),
+});
+/** Output for `role_grant_offer_decline` / `role_grant_offer_retract`. */
+export const RoleGrantOfferOkOutput = z.strictObject({ ok: z.literal(true) });
+/** Output for `role_grant_offer_list`. */
+export const RoleGrantOfferListOutput = z.strictObject({ offers: z.array(RoleGrantOfferJson) });
+/** Output for `role_grant_offer_history`. */
+export const RoleGrantOfferHistoryOutput = z.strictObject({ offers: z.array(RoleGrantOfferJson) });
+/** Output for `role_grant_revoke`. */
+export const RoleGrantRevokeOutput = z.strictObject({
+    ok: z.literal(true),
+    revoked: z.literal(true),
+});
+// -- Action specs -----------------------------------------------------------
+export const role_grant_offer_create_action_spec = {
+    method: 'role_grant_offer_create',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { account: 'required', actor: 'required' },
+    side_effects: true,
+    input: RoleGrantOfferCreateInput,
+    output: RoleGrantOfferCreateOutput,
+    async: true,
+    description: "Offer a role_grant to another account. Grantor must hold the offered role (or pass a consumer authorize callback); role's `grant_paths` must include `'admin'`.",
+    error_reasons: [
+        ERROR_ROLE_GRANT_OFFER_SELF_TARGET,
+        ERROR_ROLE_GRANT_OFFER_ROLE_NOT_GRANTABLE,
+        ERROR_ROLE_GRANT_OFFER_NOT_AUTHORIZED,
+        ERROR_ROLE_GRANT_OFFER_ACTOR_ACCOUNT_MISMATCH,
+    ],
+};
+export const role_grant_offer_accept_action_spec = {
+    method: 'role_grant_offer_accept',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { account: 'required', actor: 'required' },
+    side_effects: true,
+    input: RoleGrantOfferAcceptInput,
+    output: RoleGrantOfferAcceptOutput,
+    async: true,
+    description: 'Accept an offer. Atomically marks the offer accepted, inserts the role_grant, and supersedes sibling pending offers for the same (account, role, scope).',
+    error_reasons: [
+        ERROR_ROLE_GRANT_OFFER_NOT_FOUND,
+        ERROR_ROLE_GRANT_OFFER_TERMINAL,
+        ERROR_ROLE_GRANT_OFFER_EXPIRED,
+        ERROR_ROLE_GRANT_OFFER_ACTOR_MISMATCH,
+    ],
+};
+export const role_grant_offer_decline_action_spec = {
+    method: 'role_grant_offer_decline',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { account: 'required', actor: 'required' },
+    side_effects: true,
+    input: RoleGrantOfferDeclineInput,
+    output: RoleGrantOfferOkOutput,
+    async: true,
+    description: 'Decline an offer. Recipient-only.',
+    error_reasons: [ERROR_ROLE_GRANT_OFFER_NOT_FOUND, ERROR_ROLE_GRANT_OFFER_TERMINAL],
+};
+export const role_grant_offer_retract_action_spec = {
+    method: 'role_grant_offer_retract',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { account: 'required', actor: 'required' },
+    side_effects: true,
+    input: RoleGrantOfferRetractInput,
+    output: RoleGrantOfferOkOutput,
+    async: true,
+    description: 'Retract an offer. Grantor-only, pre-decision.',
+    error_reasons: [ERROR_ROLE_GRANT_OFFER_NOT_FOUND, ERROR_ROLE_GRANT_OFFER_TERMINAL],
+};
+export const role_grant_offer_list_action_spec = {
+    method: 'role_grant_offer_list',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { account: 'required', actor: 'required' },
+    side_effects: false,
+    input: RoleGrantOfferListInput,
+    output: RoleGrantOfferListOutput,
+    async: true,
+    description: 'List pending, non-expired offers for the caller. Admins may pass `account_id` to inspect another account.',
+};
+export const role_grant_offer_history_action_spec = {
+    method: 'role_grant_offer_history',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { account: 'required', actor: 'required' },
+    side_effects: false,
+    input: RoleGrantOfferHistoryInput,
+    output: RoleGrantOfferHistoryOutput,
+    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 role_grant_revoke_action_spec = {
+    method: 'role_grant_revoke',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { account: 'required', actor: 'required', roles: ['admin'] },
+    side_effects: true,
+    input: RoleGrantRevokeInput,
+    output: RoleGrantRevokeOutput,
+    async: true,
+    description: 'Revoke an active role_grant on a target actor. Admin-only. Supersedes any pending offers for the same (account, role, scope). Fires role_grant_revoke + role_grant_offer_supersede notifications.',
+    error_reasons: [ERROR_ROLE_GRANT_NOT_FOUND, ERROR_ROLE_NOT_WEB_GRANTABLE],
+    rate_limit: 'account',
+};
+/**
+ * All role-grant-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_role_grant_offer_action_specs = [
+    role_grant_offer_create_action_spec,
+    role_grant_offer_accept_action_spec,
+    role_grant_offer_decline_action_spec,
+    role_grant_offer_retract_action_spec,
+    role_grant_offer_list_action_spec,
+    role_grant_offer_history_action_spec,
+    role_grant_revoke_action_spec,
+];

package/dist/auth/role_grant_offer_actions.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Role grant offer RPC action handlers — the consentful-role-grants action surface.
+ *
+ * Seven actions: six offer-lifecycle methods (create / accept / decline /
+ * retract / list / history) plus `role_grant_revoke` (admin-only). All mount
+ * on a consumer's JSON-RPC endpoint via `create_rpc_endpoint`. The action
+ * specs themselves live in `auth/role_grant_offer_action_specs.ts`. Mutations
+ * declare `side_effects: true` so the RPC dispatcher wraps the handler in
+ * a DB transaction; `role_grant_offer_list` and `role_grant_offer_history` declare
+ * `side_effects: false` so they are addressable via GET.
+ *
+ * Authorization:
+ * - `role_grant_offer_create` — the grantor must hold an active role_grant for the
+ *   role being offered, and that role's `grant_paths` must include `'admin'`.
+ *   Consumers needing a richer policy (e.g., "teacher may offer student in
+ *   *their* classroom") pass an `authorize` callback that overrides the default.
+ * - `role_grant_offer_accept` / `role_grant_offer_decline` — keyed to the caller's
+ *   account; `query_*` helpers enforce the IDOR guard.
+ * - `role_grant_offer_retract` — keyed to the caller's actor.
+ * - `role_grant_offer_list` / `role_grant_offer_history` — self by default;
+ *   `{account_id}` is admin-only.
+ * - `role_grant_revoke` — spec-level `auth: {role: 'admin'}`; the RPC
+ *   dispatcher rejects non-admin callers before the handler runs.
+ *   The admin-grant-path gate prevents revoking keeper / daemon-scoped
+ *   roles via this surface. Keys on `actor_id` to survive multi-actor accounts.
+ *
+ * Audit events are emitted in-transaction by the query layer (atomic with
+ * the role_grant write on accept/revoke) or by the handler via the bound
+ * `deps.audit.emit_role_grant_target` helper for single-event lifecycle
+ * transitions. `audit.notify` (SSE/WS broadcast) fires post-commit in both
+ * paths.
+ *
+ * WS notifications fan out post-commit via `emit_after_commit` when a
+ * `notification_sender` is wired: offer lifecycle transitions notify the
+ * counterparty, `role_grant_revoke` notifies the revokee plus each superseded
+ * pending offer's grantor.
+ *
+ * @module
+ */
+import { type ActionContext, type RpcAction } from '../actions/action_rpc.js';
+import { type RoleSchemaResult } from './role_schema.js';
+import { type RequestContext } from './request_context.js';
+import type { RouteFactoryDeps } from './deps.js';
+import { type NotificationSender } from './role_grant_offer_notifications.js';
+/**
+ * Authorization callback for `role_grant_offer_create`. Returns `true` to allow,
+ * `false` to reject (handler converts to `forbidden`).
+ *
+ * Provided with the fully-resolved request context and the parsed input
+ * (pre-TTL, pre-normalization). Consumers override the default to implement
+ * policies like "teacher may offer classroom_student only in classrooms they
+ * teach".
+ */
+export type RoleGrantOfferCreateAuthorize = (auth: RequestContext, input: {
+    to_account_id: string;
+    role: string;
+    scope_id: string | null;
+}, deps: Pick<RouteFactoryDeps, 'log'>, ctx: ActionContext) => boolean | Promise<boolean>;
+/** Options for `create_role_grant_offer_actions`. */
+export interface RoleGrantOfferActionOptions {
+    /**
+     * Role schema result from `create_role_schema()`. Defaults to builtin roles only.
+     * Drives the grantability gate: a role is offerable / revocable through
+     * this surface only when its `RoleSpec.grant_paths` includes `'admin'`
+     * (the `GRANT_PATH_ADMIN` constant).
+     */
+    roles?: RoleSchemaResult;
+    /** TTL applied to newly-created offers. Defaults to `ROLE_GRANT_OFFER_DEFAULT_TTL_MS`. */
+    default_ttl_ms?: number;
+    /**
+     * Custom authorization for `role_grant_offer_create`. The default requires the
+     * caller to hold an active role_grant for the offered role *and* the role's
+     * `RoleSpec.grant_paths` to include `'admin'`. Consumers with richer
+     * policies (scope-aware, chained roles) override this.
+     */
+    authorize?: RoleGrantOfferCreateAuthorize;
+}
+/**
+ * Authorization callback that admits any admin and otherwise falls back to
+ * the symmetric default (caller must hold the offered role globally).
+ *
+ * The admin-grant-path filter in `create_handler` runs **before** the
+ * `authorize` callback, so this never sees roles whose `grant_paths`
+ * omits `'admin'`. Drop into
+ * `create_role_grant_offer_actions({authorize: authorize_admin_or_holder})`
+ * (or any factory that forwards `authorize`, e.g. `create_standard_rpc_actions`)
+ * for the common "admins offer anything; users offer what they hold"
+ * pattern. Scope-aware policies (e.g. classroom_teacher offering
+ * classroom_student in their own scope) wrap this and short-circuit `true`
+ * before delegating.
+ */
+export declare const authorize_admin_or_holder: RoleGrantOfferCreateAuthorize;
+/**
+ * Create the seven role-grant-offer RPC actions (six offer-lifecycle methods
+ * plus `role_grant_revoke`).
+ *
+ * @param deps - `RouteFactoryDeps` (`log`, `audit`, …) plus optional `notification_sender` for WS fan-out — when absent, WS fan-out is silently skipped (DB-only side effects still happen). Consumers wiring `BackendWebsocketTransport` assign its instance directly (the transport's `send_to_account` signature accepts the broader `JsonrpcMessageFromServerToClient`, which is contravariantly compatible)
+ * @param options - role schema, default TTL, authorization override
+ * @returns the `RpcAction` array to spread into a `create_rpc_endpoint` call
+ */
+export declare const create_role_grant_offer_actions: (deps: Pick<RouteFactoryDeps, "log" | "audit"> & {
+    notification_sender?: NotificationSender | null;
+}, options?: RoleGrantOfferActionOptions) => Array<RpcAction>;
+//# sourceMappingURL=role_grant_offer_actions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"role_grant_offer_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/role_grant_offer_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EAGN,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAIN,KAAK,gBAAgB,EACrB,MAAM,kBAAkB,CAAC;AA0B1B,OAAO,EAA4C,KAAK,cAAc,EAAC,MAAM,sBAAsB,CAAC;AACpG,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAEhD,OAAO,EAON,KAAK,kBAAkB,EACvB,MAAM,qCAAqC,CAAC;AAiC7C;;;;;;;;GAQG;AACH,MAAM,MAAM,6BAA6B,GAAG,CAC3C,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAAC,EACrE,IAAI,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,CAAC,EACnC,GAAG,EAAE,aAAa,KACd,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,qDAAqD;AACrD,MAAM,WAAW,2BAA2B;IAC3C;;;;;OAKG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,0FAA0F;IAC1F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,6BAA6B,CAAC;CAC1C;AA6BD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,EAAE,6BAavC,CAAC;AAIF;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,GAC3C,MAAM,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,OAAO,CAAC,GAAG;IAC/C,mBAAmB,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAChD,EACD,UAAS,2BAAgC,KACvC,KAAK,CAAC,SAAS,CAidjB,CAAC"}