@fuzdev/fuz_app 0.29.0 → 0.31.0

package/dist/auth/permit_offer_notifications.d.ts

@@ -0,0 +1,361 @@
+/**
+ * Permit offer WebSocket notification specs, builders, and the narrow
+ * `NotificationSender` interface that decouples offer/revoke send sites
+ * from `BackendWebsocketTransport`.
+ *
+ * Six `RemoteNotificationActionSpec`s cover the consentful-permits
+ * lifecycle events the server pushes to affected accounts:
+ *
+ * - `permit_offer_received` → recipient's sockets when an offer is created
+ * - `permit_offer_retracted` → recipient's sockets when a grantor retracts
+ * - `permit_offer_accepted` → grantor's sockets when the recipient accepts
+ * - `permit_offer_declined` → grantor's sockets when the recipient declines
+ * - `permit_offer_supersede` → grantor's sockets when a sibling accept or
+ *   a revoke of the resulting permit obsoletes their pending offer
+ * - `permit_revoke` → revokee's sockets when one of their active permits
+ *   is revoked (companion to the `permit_revoke` audit event)
+ *
+ * Payloads are flat and normalized — `PermitOfferJson` for the offer-lifecycle
+ * notifications (decline reason rides on `offer.decline_reason`, not a
+ * sibling field), and `{permit_id, role, scope_id, reason?}` for `permit_revoke`. The
+ * revokee/grantor/recipient account id travels via the send target (the
+ * `NotificationSender.send_to_account` argument), not in the payload.
+ *
+ * The specs surface as `EventSpec`s via `create_action_event_spec` — callers
+ * append `PERMIT_OFFER_NOTIFICATION_SPECS` to their `event_specs` on
+ * `create_app_server` so the surface reflects them and DEV-mode broadcast
+ * validation catches payload drift.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import type { EventSpec } from '../realtime/sse.js';
+import type { JsonrpcNotification } from '../http/jsonrpc.js';
+import { type Uuid } from '../uuid.js';
+/**
+ * Narrow structural capability for sending a JSON-RPC notification to every
+ * socket bound to an account.
+ *
+ * `BackendWebsocketTransport` satisfies this interface — its
+ * `send_to_account(account_id, message)` signature accepts the broader
+ * `JsonrpcMessageFromServerToClient` type, which is contravariantly
+ * compatible with `JsonrpcNotification` here. The interface stays local so
+ * handlers don't couple to the concrete transport, and tests can inject a
+ * capturing stub with no WS machinery.
+ *
+ * Returns the number of sockets the notification was sent to — callers
+ * typically ignore it (used by telemetry / tests).
+ */
+export interface NotificationSender {
+    send_to_account: (account_id: Uuid, message: JsonrpcNotification) => number;
+}
+export declare const PERMIT_OFFER_RECEIVED_NOTIFICATION_METHOD = "permit_offer_received";
+export declare const PERMIT_OFFER_RETRACTED_NOTIFICATION_METHOD = "permit_offer_retracted";
+export declare const PERMIT_OFFER_ACCEPTED_NOTIFICATION_METHOD = "permit_offer_accepted";
+export declare const PERMIT_OFFER_DECLINED_NOTIFICATION_METHOD = "permit_offer_declined";
+export declare const PERMIT_OFFER_SUPERSEDE_NOTIFICATION_METHOD = "permit_offer_supersede";
+export declare const PERMIT_REVOKE_NOTIFICATION_METHOD = "permit_revoke";
+/** Params for `permit_offer_received` — offer delivered to its recipient. */
+export declare const PermitOfferReceivedParams: 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 PermitOfferReceivedParams = z.infer<typeof PermitOfferReceivedParams>;
+/** Params for `permit_offer_retracted` — grantor-side retraction. */
+export declare const PermitOfferRetractedParams: 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 PermitOfferRetractedParams = z.infer<typeof PermitOfferRetractedParams>;
+/** Params for `permit_offer_accepted` — recipient accepted the offer. */
+export declare const PermitOfferAcceptedParams: 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 PermitOfferAcceptedParams = z.infer<typeof PermitOfferAcceptedParams>;
+/**
+ * Params for `permit_offer_declined`. The decline reason (if any) rides along
+ * inside `offer.decline_reason` — the DB stamps it on the offer row during
+ * decline, so a sibling `reason` field would just duplicate it.
+ */
+export declare const PermitOfferDeclinedParams: 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 PermitOfferDeclinedParams = z.infer<typeof PermitOfferDeclinedParams>;
+/**
+ * Params for `permit_offer_supersede`. Fires to the grantor's sockets when
+ * their pending offer is obsoleted — either by a sibling accept
+ * (`reason: 'sibling_accepted'`) or by revoke of the resulting permit
+ * (`reason: 'permit_revoked'`). `cause_id` points at the accepted offer id
+ * or the revoked permit id respectively.
+ */
+export declare const PermitOfferSupersedeParams: 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>;
+    reason: z.ZodEnum<{
+        sibling_accepted: "sibling_accepted";
+        permit_revoked: "permit_revoked";
+    }>;
+    cause_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+}, z.core.$strict>;
+export type PermitOfferSupersedeParams = z.infer<typeof PermitOfferSupersedeParams>;
+/**
+ * Params for `permit_revoke`. Delivered to the revokee's sockets when one
+ * of their active permits is revoked. Flat wire shape — `revoked_by` is
+ * admin-UI-visible but deliberately omitted here (the revokee doesn't need
+ * to learn the admin's identity). Target account is implicit in the send
+ * target.
+ */
+export declare const PermitRevokeParams: z.ZodObject<{
+    permit_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    role: z.ZodString;
+    scope_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    reason: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type PermitRevokeParams = z.infer<typeof PermitRevokeParams>;
+export declare const permit_offer_received_notification_spec: {
+    method: string;
+    kind: "remote_notification";
+    initiator: "backend";
+    auth: null;
+    side_effects: true;
+    input: 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>;
+    output: z.ZodVoid;
+    async: true;
+    description: string;
+};
+export declare const permit_offer_retracted_notification_spec: {
+    method: string;
+    kind: "remote_notification";
+    initiator: "backend";
+    auth: null;
+    side_effects: true;
+    input: 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>;
+    output: z.ZodVoid;
+    async: true;
+    description: string;
+};
+export declare const permit_offer_accepted_notification_spec: {
+    method: string;
+    kind: "remote_notification";
+    initiator: "backend";
+    auth: null;
+    side_effects: true;
+    input: 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>;
+    output: z.ZodVoid;
+    async: true;
+    description: string;
+};
+export declare const permit_offer_declined_notification_spec: {
+    method: string;
+    kind: "remote_notification";
+    initiator: "backend";
+    auth: null;
+    side_effects: true;
+    input: 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>;
+    output: z.ZodVoid;
+    async: true;
+    description: string;
+};
+export declare const permit_offer_supersede_notification_spec: {
+    method: string;
+    kind: "remote_notification";
+    initiator: "backend";
+    auth: null;
+    side_effects: true;
+    input: 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>;
+        reason: z.ZodEnum<{
+            sibling_accepted: "sibling_accepted";
+            permit_revoked: "permit_revoked";
+        }>;
+        cause_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    }, z.core.$strict>;
+    output: z.ZodVoid;
+    async: true;
+    description: string;
+};
+export declare const permit_revoke_notification_spec: {
+    method: string;
+    kind: "remote_notification";
+    initiator: "backend";
+    auth: null;
+    side_effects: true;
+    input: z.ZodObject<{
+        permit_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        role: z.ZodString;
+        scope_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+        reason: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    output: z.ZodVoid;
+    async: true;
+    description: string;
+};
+/**
+ * SSE/WS event specs for the consentful-permits notification surface.
+ *
+ * Pass to `create_app_server`'s `event_specs` so the attack surface reflects
+ * them and DEV-mode `create_validated_broadcaster` catches payload drift.
+ */
+export declare const PERMIT_OFFER_NOTIFICATION_SPECS: Array<EventSpec>;
+export declare const build_permit_offer_received_notification: (params: PermitOfferReceivedParams) => JsonrpcNotification;
+export declare const build_permit_offer_retracted_notification: (params: PermitOfferRetractedParams) => JsonrpcNotification;
+export declare const build_permit_offer_accepted_notification: (params: PermitOfferAcceptedParams) => JsonrpcNotification;
+export declare const build_permit_offer_declined_notification: (params: PermitOfferDeclinedParams) => JsonrpcNotification;
+export declare const build_permit_offer_supersede_notification: (params: PermitOfferSupersedeParams) => JsonrpcNotification;
+export declare const build_permit_revoke_notification: (params: PermitRevokeParams) => JsonrpcNotification;
+//# sourceMappingURL=permit_offer_notifications.d.ts.map

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

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

package/dist/auth/permit_offer_notifications.js

@@ -0,0 +1,179 @@
+/**
+ * Permit offer WebSocket notification specs, builders, and the narrow
+ * `NotificationSender` interface that decouples offer/revoke send sites
+ * from `BackendWebsocketTransport`.
+ *
+ * Six `RemoteNotificationActionSpec`s cover the consentful-permits
+ * lifecycle events the server pushes to affected accounts:
+ *
+ * - `permit_offer_received` → recipient's sockets when an offer is created
+ * - `permit_offer_retracted` → recipient's sockets when a grantor retracts
+ * - `permit_offer_accepted` → grantor's sockets when the recipient accepts
+ * - `permit_offer_declined` → grantor's sockets when the recipient declines
+ * - `permit_offer_supersede` → grantor's sockets when a sibling accept or
+ *   a revoke of the resulting permit obsoletes their pending offer
+ * - `permit_revoke` → revokee's sockets when one of their active permits
+ *   is revoked (companion to the `permit_revoke` audit event)
+ *
+ * Payloads are flat and normalized — `PermitOfferJson` for the offer-lifecycle
+ * notifications (decline reason rides on `offer.decline_reason`, not a
+ * sibling field), and `{permit_id, role, scope_id, reason?}` for `permit_revoke`. The
+ * revokee/grantor/recipient account id travels via the send target (the
+ * `NotificationSender.send_to_account` argument), not in the payload.
+ *
+ * The specs surface as `EventSpec`s via `create_action_event_spec` — callers
+ * append `PERMIT_OFFER_NOTIFICATION_SPECS` to their `event_specs` on
+ * `create_app_server` so the surface reflects them and DEV-mode broadcast
+ * validation catches payload drift.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { create_action_event_spec } from '../actions/action_bridge.js';
+import { create_jsonrpc_notification } from '../http/jsonrpc_helpers.js';
+import { Uuid as UuidSchema } from '../uuid.js';
+import { RoleName } from './role_schema.js';
+import { PermitOfferJson } from './permit_offer_schema.js';
+import { PERMIT_REVOKED_REASON_LENGTH_MAX } from './account_schema.js';
+// -- Method constants -------------------------------------------------------
+export const PERMIT_OFFER_RECEIVED_NOTIFICATION_METHOD = 'permit_offer_received';
+export const PERMIT_OFFER_RETRACTED_NOTIFICATION_METHOD = 'permit_offer_retracted';
+export const PERMIT_OFFER_ACCEPTED_NOTIFICATION_METHOD = 'permit_offer_accepted';
+export const PERMIT_OFFER_DECLINED_NOTIFICATION_METHOD = 'permit_offer_declined';
+export const PERMIT_OFFER_SUPERSEDE_NOTIFICATION_METHOD = 'permit_offer_supersede';
+export const PERMIT_REVOKE_NOTIFICATION_METHOD = 'permit_revoke';
+// -- Params schemas ---------------------------------------------------------
+/** Params for `permit_offer_received` — offer delivered to its recipient. */
+export const PermitOfferReceivedParams = z.strictObject({
+    offer: PermitOfferJson,
+});
+/** Params for `permit_offer_retracted` — grantor-side retraction. */
+export const PermitOfferRetractedParams = z.strictObject({
+    offer: PermitOfferJson,
+});
+/** Params for `permit_offer_accepted` — recipient accepted the offer. */
+export const PermitOfferAcceptedParams = z.strictObject({
+    offer: PermitOfferJson,
+});
+/**
+ * Params for `permit_offer_declined`. The decline reason (if any) rides along
+ * inside `offer.decline_reason` — the DB stamps it on the offer row during
+ * decline, so a sibling `reason` field would just duplicate it.
+ */
+export const PermitOfferDeclinedParams = z.strictObject({
+    offer: PermitOfferJson,
+});
+/**
+ * Params for `permit_offer_supersede`. Fires to the grantor's sockets when
+ * their pending offer is obsoleted — either by a sibling accept
+ * (`reason: 'sibling_accepted'`) or by revoke of the resulting permit
+ * (`reason: 'permit_revoked'`). `cause_id` points at the accepted offer id
+ * or the revoked permit id respectively.
+ */
+export const PermitOfferSupersedeParams = z.strictObject({
+    offer: PermitOfferJson,
+    reason: z.enum(['sibling_accepted', 'permit_revoked']),
+    cause_id: UuidSchema,
+});
+/**
+ * Params for `permit_revoke`. Delivered to the revokee's sockets when one
+ * of their active permits is revoked. Flat wire shape — `revoked_by` is
+ * admin-UI-visible but deliberately omitted here (the revokee doesn't need
+ * to learn the admin's identity). Target account is implicit in the send
+ * target.
+ */
+export const PermitRevokeParams = z.strictObject({
+    permit_id: UuidSchema,
+    role: RoleName,
+    scope_id: UuidSchema.nullable(),
+    reason: z.string().max(PERMIT_REVOKED_REASON_LENGTH_MAX).nullable(),
+});
+// -- Action specs -----------------------------------------------------------
+export const permit_offer_received_notification_spec = {
+    method: PERMIT_OFFER_RECEIVED_NOTIFICATION_METHOD,
+    kind: 'remote_notification',
+    initiator: 'backend',
+    auth: null,
+    side_effects: true,
+    input: PermitOfferReceivedParams,
+    output: z.void(),
+    async: true,
+    description: 'A new permit offer arrived in the recipient’s inbox.',
+};
+export const permit_offer_retracted_notification_spec = {
+    method: PERMIT_OFFER_RETRACTED_NOTIFICATION_METHOD,
+    kind: 'remote_notification',
+    initiator: 'backend',
+    auth: null,
+    side_effects: true,
+    input: PermitOfferRetractedParams,
+    output: z.void(),
+    async: true,
+    description: 'A pending permit offer was retracted by its grantor.',
+};
+export const permit_offer_accepted_notification_spec = {
+    method: PERMIT_OFFER_ACCEPTED_NOTIFICATION_METHOD,
+    kind: 'remote_notification',
+    initiator: 'backend',
+    auth: null,
+    side_effects: true,
+    input: PermitOfferAcceptedParams,
+    output: z.void(),
+    async: true,
+    description: 'A pending permit offer was accepted by its recipient.',
+};
+export const permit_offer_declined_notification_spec = {
+    method: PERMIT_OFFER_DECLINED_NOTIFICATION_METHOD,
+    kind: 'remote_notification',
+    initiator: 'backend',
+    auth: null,
+    side_effects: true,
+    input: PermitOfferDeclinedParams,
+    output: z.void(),
+    async: true,
+    description: 'A pending permit offer was declined by its recipient.',
+};
+export const permit_offer_supersede_notification_spec = {
+    method: PERMIT_OFFER_SUPERSEDE_NOTIFICATION_METHOD,
+    kind: 'remote_notification',
+    initiator: 'backend',
+    auth: null,
+    side_effects: true,
+    input: PermitOfferSupersedeParams,
+    output: z.void(),
+    async: true,
+    description: 'A grantor’s pending permit offer was obsoleted by a sibling accept or by revoke of the resulting permit.',
+};
+export const permit_revoke_notification_spec = {
+    method: PERMIT_REVOKE_NOTIFICATION_METHOD,
+    kind: 'remote_notification',
+    initiator: 'backend',
+    auth: null,
+    side_effects: true,
+    input: PermitRevokeParams,
+    output: z.void(),
+    async: true,
+    description: 'An active permit on the revokee’s account was revoked.',
+};
+// -- EventSpec surface ------------------------------------------------------
+/**
+ * SSE/WS event specs for the consentful-permits notification surface.
+ *
+ * Pass to `create_app_server`'s `event_specs` so the attack surface reflects
+ * them and DEV-mode `create_validated_broadcaster` catches payload drift.
+ */
+export const PERMIT_OFFER_NOTIFICATION_SPECS = [
+    create_action_event_spec(permit_offer_received_notification_spec),
+    create_action_event_spec(permit_offer_retracted_notification_spec),
+    create_action_event_spec(permit_offer_accepted_notification_spec),
+    create_action_event_spec(permit_offer_declined_notification_spec),
+    create_action_event_spec(permit_offer_supersede_notification_spec),
+    create_action_event_spec(permit_revoke_notification_spec),
+];
+// -- Notification builders --------------------------------------------------
+export const build_permit_offer_received_notification = (params) => create_jsonrpc_notification(PERMIT_OFFER_RECEIVED_NOTIFICATION_METHOD, params);
+export const build_permit_offer_retracted_notification = (params) => create_jsonrpc_notification(PERMIT_OFFER_RETRACTED_NOTIFICATION_METHOD, params);
+export const build_permit_offer_accepted_notification = (params) => create_jsonrpc_notification(PERMIT_OFFER_ACCEPTED_NOTIFICATION_METHOD, params);
+export const build_permit_offer_declined_notification = (params) => create_jsonrpc_notification(PERMIT_OFFER_DECLINED_NOTIFICATION_METHOD, params);
+export const build_permit_offer_supersede_notification = (params) => create_jsonrpc_notification(PERMIT_OFFER_SUPERSEDE_NOTIFICATION_METHOD, params);
+export const build_permit_revoke_notification = (params) => create_jsonrpc_notification(PERMIT_REVOKE_NOTIFICATION_METHOD, params);