@fuzdev/fuz_app 0.43.0 → 0.44.0

package/dist/actions/CLAUDE.md

@@ -591,6 +591,83 @@ Cast the return to a generated `ActionsApi` interface for full typing:
 codegen via `generate_actions_api_method_signature` keeps the shape
 consistent. See ../../docs/usage.md §Typed Client Codegen.
 
+### Throwing variants — `create_throwing_rpc_call` + `create_throwing_api`
+
+Two helpers wrap a typed `create_rpc_client` Proxy so `{ok: false}` results
+throw an `Error` with `{code, message, data?}` (catch blocks read
+`err.data?.reason` — optional chaining required because JSON-RPC `data`
+is spec-level optional). Same hardening on both: only `{code, data}` cross
+onto the Error, leaving `name` / `stack` as the native Error's own so
+attacker-shaped `result.error` payloads cannot overwrite them.
+
+| Helper                     | Shape                            | Use at                                                                     |
+| -------------------------- | -------------------------------- | -------------------------------------------------------------------------- |
+| `create_throwing_rpc_call` | `(method, input?) => Promise<T>` | adapter wiring (e.g. `ui/admin_rpc_adapters.ts`) — method comes from a map |
+| `create_throwing_api`      | typed Proxy over `ActionsApi`    | direct call sites — `await api.foo(input)` keeps full inference            |
+
+**Recommended consumer convention.** The throwing form is the common
+case at call sites; the Result form is the composable escape hatch for
+sites that want to inspect `error.data.reason` without try/catch. Bind
+them as `api` (throwing wrapper) and `api_raw` (the unwrapped
+underlying, returning Results):
+
+```ts
+const api_raw = create_rpc_client({peer, environment}) as unknown as MyActionsApi;
+const api = create_throwing_api(api_raw);
+// hot path:    await api.foo(input)
+// rare branch: const r = await api_raw.foo(input); if (!r.ok) { … }
+```
+
+Composable — feed the same typed Proxy into both: the loose method-keyed
+form for adapter dispatch, the typed Proxy form for hand-written call
+sites. `ThrowingApi<TApi>` mapped type strips
+`Promise<Result<{value: T}, {error: JsonrpcErrorObject}>>` to `Promise<T>`
+on every method that matches the `request_response` / async `local_call`
+return shape; `remote_notification` (`=> void`) and sync `local_call`
+methods pass through. The Proxy implementation inspects each call's
+result shape at runtime and only unwraps when it sees a Result, so
+non-Result returns flow through unchanged.
+
+Both helpers throw `"rpc method not found: <name>"` on invocation of an
+unknown method. For `create_throwing_api` the thrower is returned from
+the Proxy get trap so `api.missing()` errors with the same clear
+message rather than the JS default `"api.missing is not a function"`.
+Symbol props and `then` stay `undefined` so the Proxy doesn't get
+probed as a thenable by `await`.
+
+### Frontend factory (`frontend_rpc_client.ts`)
+
+`create_frontend_rpc_client<TApi>({specs, path?, transports?})` bundles
+the `ActionRegistry + ActionEventEnvironment + Transports + ActionPeer +
+create_rpc_client` boilerplate every consumer repeats — plus the
+`lookup_action_handler: () => undefined` stub (frontend never registers
+`request_response` handlers; every method dispatches over the wire).
+The `as unknown as TApi` cast happens inside the helper, so call sites
+get a typed return without the cast hostility. Returns
+`{api, peer, environment}` so advanced consumers (zzz-style frontends
+needing extra transports / WS notification handlers / action-history
+wiring) can extend without recreating the bundle.
+
+Default transport is `FrontendHttpTransport(path ?? '/api/rpc')`. Pass
+`transports` for WS-first or mixed setups — when supplied, the default
+HTTP transport is **not** registered. `local_call` specs in `specs`
+silently no-op because `lookup_action_handler` always returns
+`undefined`; this factory targets wire-dispatched actions.
+
+Pair with `create_throwing_api` to land the recommended `api` /
+`api_raw` convention in two lines:
+
+```ts
+const {api: api_raw} = create_frontend_rpc_client<MyActionsApi>({
+	specs: all_standard_action_specs,
+});
+const api = create_throwing_api(api_raw);
+```
+
+`all_standard_action_specs` (in `../auth/standard_action_specs.ts`) is
+the matching aggregate spec list mirroring `create_standard_rpc_actions`
+on the backend — see `../auth/CLAUDE.md` §`standard_rpc_actions.ts`.
+
 ## Broadcast API (`broadcast_api.ts`)
 
 `create_broadcast_api({peer, specs, log?, should_deliver?})` — builds a

package/dist/actions/frontend_rpc_client.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Frontend-only typed RPC client factory.
+ *
+ * Bundles the `ActionRegistry + ActionEventEnvironment + Transports +
+ * ActionPeer + create_rpc_client` boilerplate every consumer repeats — plus
+ * the `lookup_action_handler: () => undefined` stub (frontend never registers
+ * `request_response` handlers; every method dispatches over the wire).
+ *
+ * Generic `TApi` is the consumer's typed Proxy interface. The `as unknown
+ * as TApi` double cast happens inside the helper so call sites get a typed
+ * return value without the cast hostility.
+ *
+ * Companion to `create_throwing_api` — typical wiring is two lines:
+ *
+ * ```ts
+ * const {api: api_raw} = create_frontend_rpc_client<MyActionsApi>({specs: all_specs});
+ * const api = create_throwing_api(api_raw);
+ * ```
+ *
+ * Returns the underlying `peer` and `environment` alongside `api` so
+ * advanced consumers (zzz-style frontends needing extra transports / WS
+ * notification handlers / action-history wiring) can extend without
+ * recreating the bundle.
+ *
+ * Note: `local_call` specs in `specs` will silently no-op because
+ * `lookup_action_handler` always returns `undefined` — the frontend
+ * factory is for wire-dispatched actions. Frontend-side `local_call`
+ * needs a different wiring shape (custom `environment.lookup_action_handler`).
+ *
+ * @module
+ */
+import { ActionPeer } from './action_peer.js';
+import { type Transport } from './transports.js';
+import type { ActionEventEnvironment } from './action_event_types.js';
+import type { ActionSpecUnion } from './action_spec.js';
+/** Options for `create_frontend_rpc_client`. */
+export interface CreateFrontendRpcClientOptions {
+    /**
+     * Action specs the typed Proxy can dispatch. Methods absent from this
+     * list silently return `undefined` from the Proxy — the generic `TApi`
+     * cannot constrain runtime membership, so consumers must keep this list
+     * in sync with the typed surface (codegen recommended).
+     */
+    specs: ReadonlyArray<ActionSpecUnion>;
+    /**
+     * HTTP RPC endpoint path for the default `FrontendHttpTransport`.
+     * Defaults to `/api/rpc`. Ignored when `transports` is provided.
+     */
+    path?: string;
+    /**
+     * Optional explicit transport list. When provided, the default
+     * `FrontendHttpTransport(path)` is **not** registered — the caller is
+     * responsible for at least one ready transport. Use for WS-first or
+     * WS+HTTP mixed setups.
+     */
+    transports?: ReadonlyArray<Transport>;
+}
+/** Bundle returned by `create_frontend_rpc_client`. */
+export interface FrontendRpcClient<TApi> {
+    /** Typed Proxy — call `api.method(input)` for `Promise<Result<...>>`. */
+    api: TApi;
+    /** Underlying peer — exposed for consumers that need to register more transports or send raw messages. */
+    peer: ActionPeer;
+    /** Action environment — exposed for consumers that need to share it (e.g. attach a notification handler registry). */
+    environment: ActionEventEnvironment;
+}
+/**
+ * Build a frontend-only typed RPC client.
+ *
+ * @param options - `specs` (required), optional `path` / `transports`
+ * @returns `{api, peer, environment}` — typed Proxy plus the underlying primitives
+ */
+export declare const create_frontend_rpc_client: <TApi>(options: CreateFrontendRpcClientOptions) => FrontendRpcClient<TApi>;
+//# sourceMappingURL=frontend_rpc_client.d.ts.map

package/dist/actions/frontend_rpc_client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontend_rpc_client.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/frontend_rpc_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAa,KAAK,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAG3D,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AACpE,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAEtD,gDAAgD;AAChD,MAAM,WAAW,8BAA8B;IAC9C;;;;;OAKG;IACH,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACtC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;CACtC;AAED,uDAAuD;AACvD,MAAM,WAAW,iBAAiB,CAAC,IAAI;IACtC,yEAAyE;IACzE,GAAG,EAAE,IAAI,CAAC;IACV,0GAA0G;IAC1G,IAAI,EAAE,UAAU,CAAC;IACjB,sHAAsH;IACtH,WAAW,EAAE,sBAAsB,CAAC;CACpC;AAED;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,GAAI,IAAI,EAC9C,SAAS,8BAA8B,KACrC,iBAAiB,CAAC,IAAI,CAgBxB,CAAC"}

package/dist/actions/frontend_rpc_client.js

@@ -0,0 +1,61 @@
+/**
+ * Frontend-only typed RPC client factory.
+ *
+ * Bundles the `ActionRegistry + ActionEventEnvironment + Transports +
+ * ActionPeer + create_rpc_client` boilerplate every consumer repeats — plus
+ * the `lookup_action_handler: () => undefined` stub (frontend never registers
+ * `request_response` handlers; every method dispatches over the wire).
+ *
+ * Generic `TApi` is the consumer's typed Proxy interface. The `as unknown
+ * as TApi` double cast happens inside the helper so call sites get a typed
+ * return value without the cast hostility.
+ *
+ * Companion to `create_throwing_api` — typical wiring is two lines:
+ *
+ * ```ts
+ * const {api: api_raw} = create_frontend_rpc_client<MyActionsApi>({specs: all_specs});
+ * const api = create_throwing_api(api_raw);
+ * ```
+ *
+ * Returns the underlying `peer` and `environment` alongside `api` so
+ * advanced consumers (zzz-style frontends needing extra transports / WS
+ * notification handlers / action-history wiring) can extend without
+ * recreating the bundle.
+ *
+ * Note: `local_call` specs in `specs` will silently no-op because
+ * `lookup_action_handler` always returns `undefined` — the frontend
+ * factory is for wire-dispatched actions. Frontend-side `local_call`
+ * needs a different wiring shape (custom `environment.lookup_action_handler`).
+ *
+ * @module
+ */
+import { ActionRegistry } from './action_registry.js';
+import { ActionPeer } from './action_peer.js';
+import { Transports } from './transports.js';
+import { FrontendHttpTransport } from './transports_http.js';
+import { create_rpc_client } from './rpc_client.js';
+/**
+ * Build a frontend-only typed RPC client.
+ *
+ * @param options - `specs` (required), optional `path` / `transports`
+ * @returns `{api, peer, environment}` — typed Proxy plus the underlying primitives
+ */
+export const create_frontend_rpc_client = (options) => {
+    const registry = new ActionRegistry([...options.specs]);
+    const environment = {
+        executor: 'frontend',
+        lookup_action_spec: (method) => registry.spec_by_method.get(method),
+        lookup_action_handler: () => undefined,
+    };
+    const transports = new Transports();
+    if (options.transports) {
+        for (const t of options.transports)
+            transports.register_transport(t);
+    }
+    else {
+        transports.register_transport(new FrontendHttpTransport(options.path ?? '/api/rpc'));
+    }
+    const peer = new ActionPeer({ environment, transports });
+    const api = create_rpc_client({ peer, environment });
+    return { api, peer, environment };
+};

package/dist/actions/rpc_client.d.ts

@@ -9,10 +9,12 @@
  *
  * @module
  */
+import type { Result } from '@fuzdev/fuz_util/result.js';
 import type { ActionEventEnvironment } from './action_event_types.js';
 import type { ActionPeer, ActionPeerSendOptions } from './action_peer.js';
 import type { ActionEventDataUnion } from './action_event_data.js';
 import type { TransportName } from './transports.js';
+import type { JsonrpcErrorObject } from '../http/jsonrpc.js';
 /**
  * Optional per-method transport selector. Return the transport to use for a
  * given method, or `undefined` to let the peer pick via its fallback rules.
@@ -113,4 +115,66 @@ export type ThrowingRpcCall = <TOutput = unknown>(method: string, input?: unknow
  *   notably the consumer's generated `ActionsApi` interface)
  */
 export declare const create_throwing_rpc_call: <TApi extends Record<keyof TApi, (input?: any) => Promise<any> | void>>(api: TApi) => ThrowingRpcCall;
+/**
+ * Maps a typed `ActionsApi` to a throwing variant.
+ *
+ * For each method whose return type matches the `create_rpc_client` shape
+ * (`Promise<Result<{value: T}, {error: JsonrpcErrorObject}>>`), the wrapped
+ * method returns `Promise<T>` directly. Other shapes (notifications typed
+ * as `=> void`, sync `local_call` methods) pass through unchanged — there
+ * is nothing to unwrap.
+ *
+ * Input + options parameters are preserved verbatim so generics, branded
+ * Uuids, and per-call `RpcClientCallOptions` keep working.
+ */
+export type ThrowingApi<TApi> = {
+    [K in keyof TApi]: TApi[K] extends (input?: infer TInput, options?: infer TOptions) => Promise<Result<{
+        value: infer TValue;
+    }, {
+        error: JsonrpcErrorObject;
+    }>> ? (input?: TInput, options?: TOptions) => Promise<TValue> : TApi[K];
+};
+/**
+ * Wrap a typed RPC client so every call resolves to its unwrapped value or
+ * throws an `Error` carrying the JSON-RPC `{code, message, data?}` shape.
+ *
+ * Implementation is a Proxy because the underlying `create_rpc_client`
+ * return is itself a Proxy with no concrete keys — a key-by-key wrap would
+ * need to enumerate the typed surface, which only the consumer's generated
+ * `ActionsApi` interface knows.
+ *
+ * Pass-through on non-Result returns is deliberate: sync `local_call`
+ * Proxy methods return values directly (see `create_sync_local_call_method`
+ * above). The Proxy can't distinguish those at get-time, so the wrapper
+ * inspects `result` shape at call-time and only unwraps when it sees a
+ * Result. Non-object returns pass through unchanged.
+ *
+ * Only `{code, data}` cross onto the thrown Error — `name` / `stack` are
+ * left as the Error's own properties so attacker-shaped `result.error`
+ * payloads cannot overwrite them. Same hardening as
+ * `create_throwing_rpc_call`.
+ *
+ * Composable with `create_throwing_rpc_call` — same typed underlying
+ * client feeds both: the Proxy form for direct call sites, the loose
+ * method-keyed form for adapter wiring (`ui/admin_rpc_adapters.ts`).
+ *
+ * Recommended consumer convention: bind the throwing wrapper to `api`
+ * (the common case at call sites) and the underlying Result-returning
+ * Proxy to `api_raw` (the composable escape hatch for callers that
+ * want to inspect `error.data.reason` without try/catch).
+ *
+ * Catch blocks read `err.data?.reason` — optional chaining required
+ * because JSON-RPC `data` is spec-level optional.
+ *
+ * On unknown string-keyed methods, the get trap returns a function that
+ * throws `"rpc method not found: <prop>"` on invocation — symmetric with
+ * `create_throwing_rpc_call` and clearer than the JS default
+ * `"api.foo is not a function"`. Symbol props and `then` stay
+ * undefined so the Proxy isn't accidentally treated as a thenable
+ * (`await api` would otherwise probe `then` and trip the thrower).
+ *
+ * @param api_raw - typed RPC client from `create_rpc_client`, cast
+ *   to a consumer-generated `ActionsApi` interface
+ */
+export declare const create_throwing_api: <TApi extends object>(api_raw: TApi) => ThrowingApi<TApi>;
 //# sourceMappingURL=rpc_client.d.ts.map

package/dist/actions/rpc_client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rpc_client.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/rpc_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AAOpE,OAAO,KAAK,EAAC,UAAU,EAAE,qBAAqB,EAAC,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAGnD;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAC;AAM/E,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACtC,aAAa,EAAE,CAAC,IAAI,EAAE;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,oBAAoB,CAAA;KAAC,KAC5E;QACA,sBAAsB,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;KAC5C,GACD,SAAS,CAAC;CACb;AAED,uCAAuC;AACvC,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,sBAAsB,CAAC;IACpC,kEAAkE;IAClE,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,kBAAkB,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAC7B,SAAS,sBAAsB,KAC7B,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG,CAgB7C,CAAC;AA2DF;;;;;GAKG;AACH,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;CAAG;AAgItE;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,GAAG,OAAO,EAC/C,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,OAAO,KACX,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,wBAAwB,GACpC,IAAI,SAAS,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,EAErE,KAAK,IAAI,KACP,eAcF,CAAC"}
+{"version":3,"file":"rpc_client.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/rpc_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,4BAA4B,CAAC;AAQvD,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AAOpE,OAAO,KAAK,EAAC,UAAU,EAAE,qBAAqB,EAAC,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAEnD,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,oBAAoB,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAC;AAM/E,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACtC,aAAa,EAAE,CAAC,IAAI,EAAE;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,oBAAoB,CAAA;KAAC,KAC5E;QACA,sBAAsB,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;KAC5C,GACD,SAAS,CAAC;CACb;AAED,uCAAuC;AACvC,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,sBAAsB,CAAC;IACpC,kEAAkE;IAClE,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,kBAAkB,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAC7B,SAAS,sBAAsB,KAC7B,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG,CAgB7C,CAAC;AA2DF;;;;;GAKG;AACH,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;CAAG;AAgItE;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,GAAG,OAAO,EAC/C,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,OAAO,KACX,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,wBAAwB,GACpC,IAAI,SAAS,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,EAErE,KAAK,IAAI,KACP,eAcF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,CAAC,IAAI,IAAI;KAC9B,CAAC,IAAI,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,SAAS,CAClC,KAAK,CAAC,EAAE,MAAM,MAAM,EACpB,OAAO,CAAC,EAAE,MAAM,QAAQ,KACpB,OAAO,CAAC,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,MAAM,CAAA;KAAC,EAAE;QAAC,KAAK,EAAE,kBAAkB,CAAA;KAAC,CAAC,CAAC,GACrE,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,KAAK,OAAO,CAAC,MAAM,CAAC,GACvD,IAAI,CAAC,CAAC,CAAC;CACV,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,mBAAmB,GAAI,IAAI,SAAS,MAAM,EAAE,SAAS,IAAI,KAAG,WAAW,CAAC,IAAI,CA8BxF,CAAC"}

package/dist/actions/rpc_client.js

@@ -222,3 +222,80 @@ export const create_throwing_rpc_call = (api) => {
         return result.value;
     };
 };
+/**
+ * Wrap a typed RPC client so every call resolves to its unwrapped value or
+ * throws an `Error` carrying the JSON-RPC `{code, message, data?}` shape.
+ *
+ * Implementation is a Proxy because the underlying `create_rpc_client`
+ * return is itself a Proxy with no concrete keys — a key-by-key wrap would
+ * need to enumerate the typed surface, which only the consumer's generated
+ * `ActionsApi` interface knows.
+ *
+ * Pass-through on non-Result returns is deliberate: sync `local_call`
+ * Proxy methods return values directly (see `create_sync_local_call_method`
+ * above). The Proxy can't distinguish those at get-time, so the wrapper
+ * inspects `result` shape at call-time and only unwraps when it sees a
+ * Result. Non-object returns pass through unchanged.
+ *
+ * Only `{code, data}` cross onto the thrown Error — `name` / `stack` are
+ * left as the Error's own properties so attacker-shaped `result.error`
+ * payloads cannot overwrite them. Same hardening as
+ * `create_throwing_rpc_call`.
+ *
+ * Composable with `create_throwing_rpc_call` — same typed underlying
+ * client feeds both: the Proxy form for direct call sites, the loose
+ * method-keyed form for adapter wiring (`ui/admin_rpc_adapters.ts`).
+ *
+ * Recommended consumer convention: bind the throwing wrapper to `api`
+ * (the common case at call sites) and the underlying Result-returning
+ * Proxy to `api_raw` (the composable escape hatch for callers that
+ * want to inspect `error.data.reason` without try/catch).
+ *
+ * Catch blocks read `err.data?.reason` — optional chaining required
+ * because JSON-RPC `data` is spec-level optional.
+ *
+ * On unknown string-keyed methods, the get trap returns a function that
+ * throws `"rpc method not found: <prop>"` on invocation — symmetric with
+ * `create_throwing_rpc_call` and clearer than the JS default
+ * `"api.foo is not a function"`. Symbol props and `then` stay
+ * undefined so the Proxy isn't accidentally treated as a thenable
+ * (`await api` would otherwise probe `then` and trip the thrower).
+ *
+ * @param api_raw - typed RPC client from `create_rpc_client`, cast
+ *   to a consumer-generated `ActionsApi` interface
+ */
+export const create_throwing_api = (api_raw) => {
+    return new Proxy(api_raw, {
+        get(target, prop) {
+            const fn = target[prop];
+            if (typeof fn === 'function') {
+                return async (...args) => {
+                    const result = await fn.apply(target, args);
+                    if (result === null || typeof result !== 'object')
+                        return result;
+                    const r = result;
+                    if (r.ok === true)
+                        return r.value;
+                    if (r.ok === false && r.error && typeof r.error === 'object') {
+                        const e = r.error;
+                        throw Object.assign(new Error(e.message), {
+                            code: e.code,
+                            data: e.data,
+                        });
+                    }
+                    return result;
+                };
+            }
+            if (fn !== undefined)
+                return fn;
+            // Underlying api has no member by this name. Symbol props and
+            // `then` must stay undefined — `await tapi` reads `then` and
+            // would otherwise trip the thrower.
+            if (typeof prop !== 'string' || prop === 'then')
+                return undefined;
+            return () => {
+                throw new Error(`rpc method not found: ${prop}`);
+            };
+        },
+    });
+};

package/dist/auth/CLAUDE.md

@@ -1039,6 +1039,14 @@ the admin integration suite exercises `account_token_create` /
 consumer wiring the admin surface without account actions will hit
 `method not found` on first admin-suite run.
 
+Frontend mirror: `all_standard_action_specs` (in
+`./standard_action_specs.ts`) bundles `all_admin_action_specs +
+all_permit_offer_action_specs + all_account_action_specs` into one
+`ReadonlyArray<RequestResponseActionSpec>` for typed-client codegen
+and `create_frontend_rpc_client({specs})` wiring. Self-service role
+specs are not included (opt-in, app-specific `eligible_roles`) —
+spread `all_self_service_role_action_specs` separately when needed.
+
 ### `account_action_specs.ts` + `account_actions.ts` — seven self-service RPC actions
 
 Counterpart to `account_routes.ts`. Cookie-lifecycle flows (`login`,
@@ -1084,15 +1092,17 @@ registry of all seven specs.
 ### `self_service_role_action_specs.ts` + `self_service_role_actions.ts` — opt-in self-service role toggle
 
 Same split as the other registries: `*_action_specs.ts` holds the input/output
-Zod schemas, the two `satisfies RequestResponseActionSpec` literals, the
+Zod schemas, the `satisfies RequestResponseActionSpec` literal, the
 `ERROR_ROLE_NOT_SELF_SERVICE_ELIGIBLE` reason constant, and the
 `all_self_service_role_action_specs` registry — all client-safe. The
-`*_actions.ts` factory imports the specs and pairs them with handlers.
-
-Two static `request_response` actions — `self_service_role_grant` and
-`self_service_role_revoke` — that take `{role}` as input and toggle a
-global permit on the caller. Both are idempotent: `granted: false` when
-the caller already holds the role, `revoked: false` when they don't.
+`*_actions.ts` factory imports the spec and pairs it with the handler.
+
+One static `request_response` action — `self_service_role_set` — that
+takes `{role, enabled: boolean}` and toggles a global permit on the
+caller. Idempotent in both directions: `changed: false` when the
+post-call state already matched the request (already-held when
+enabling; not-held when disabling). Output is `{ok, enabled, changed}` —
+`enabled` echoes the post-call state for self-describing responses.
 Audit metadata carries `self_service: true` so admin reviewers can
 distinguish self-toggled permits from admin grants/offers. The
 `permit_grant` / `permit_revoke` metadata schemas declare
@@ -1100,7 +1110,7 @@ distinguish self-toggled permits from admin grants/offers. The
 part of the documented surface rather than riding on `z.looseObject`
 permissiveness.
 
-Method names are static — `role` lives in the input, not the method
+Method name is static — `role` lives in the input, not the method
 name. Mirrors the `permit_offer_create({role})` precedent. Per-role
 parameterized methods would break the `satisfies RequestResponseActionSpec`
 codegen invariant and grow the surface linearly per role.
@@ -1110,14 +1120,15 @@ codegen invariant and grow the surface linearly per role.
 - `eligible_roles: ReadonlyArray<string>` — required allowlist. Roles
   outside the list are rejected with `forbidden` + reason
   `role_not_self_service_eligible` (exported as
-  `ERROR_ROLE_NOT_SELF_SERVICE_ELIGIBLE`).
+  `ERROR_ROLE_NOT_SELF_SERVICE_ELIGIBLE`). The eligibility check fires
+  before the `enabled` branch — same rejection regardless of direction.
 - `roles?: RoleSchemaResult` — optional. When supplied, every entry in
   `eligible_roles` is checked against `roles.role_options` at factory
   time so typos throw at startup instead of at first call.
 
-Grant path uses `query_permit_has_role` for a benign-TOCTOU pre-check
+Grant branch uses `query_permit_has_role` for a benign-TOCTOU pre-check
 (distinguishes new grant from idempotent re-grant), then
-`query_grant_permit` for the actual insert. Revoke path filters
+`query_grant_permit` for the actual insert. Revoke branch filters
 `query_permit_find_active_for_actor` in JS for the matching
 `(actor, role, scope_id IS NULL)` row before calling
 `query_revoke_permit`. Bundle is **not** included in
@@ -1126,8 +1137,8 @@ spread alongside the standard bundle when needed.
 
 Deps: `SelfServiceRoleActionDeps = Pick<RouteFactoryDeps, 'log' | 'on_audit_event' | 'audit_log_config'>`.
 
-`all_self_service_role_action_specs: Array<RequestResponseActionSpec>` —
-codegen-ready registry of both specs.
+`all_self_service_role_action_specs: ReadonlyArray<RequestResponseActionSpec>` —
+codegen-ready registry of the single unified spec.
 
 ## Cleanup
 

package/dist/auth/self_service_role_action_specs.d.ts

@@ -1,5 +1,5 @@
 /**
- * Self-service role grant/revoke action specs — schemas, error reasons,
+ * Unified self-service role toggle action spec — schemas, error reasons,
  * and the codegen-ready registry.
  *
  * Client-safe: no query-layer or audit-write imports. Handler factory
@@ -11,54 +11,24 @@ import { z } from 'zod';
 import type { RequestResponseActionSpec } from '../actions/action_spec.js';
 /** Error reason — caller asked to self-toggle a role outside the configured allowlist. */
 export declare const ERROR_ROLE_NOT_SELF_SERVICE_ELIGIBLE: "role_not_self_service_eligible";
-/** Input for `self_service_role_grant`. */
-export declare const SelfServiceRoleGrantInput: z.ZodObject<{
+/** Input for `self_service_role_set`. */
+export declare const SelfServiceRoleSetInput: z.ZodObject<{
     role: z.ZodString;
+    enabled: z.ZodBoolean;
 }, z.core.$strict>;
-export type SelfServiceRoleGrantInput = z.infer<typeof SelfServiceRoleGrantInput>;
+export type SelfServiceRoleSetInput = z.infer<typeof SelfServiceRoleSetInput>;
 /**
- * Output for `self_service_role_grant`. `granted` is `false` on idempotent
- * re-grant (caller already held the role globally); `permit_id` is set on
- * new grants only.
+ * Output for `self_service_role_set`. `enabled` echoes the post-call state
+ * (always equals the input `enabled` on success). `changed` is `true` only
+ * when the call mutated — re-grants / re-revokes return `false`.
  */
-export declare const SelfServiceRoleGrantOutput: z.ZodObject<{
+export declare const SelfServiceRoleSetOutput: z.ZodObject<{
     ok: z.ZodLiteral<true>;
-    granted: z.ZodBoolean;
-    permit_id: z.ZodOptional<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    enabled: z.ZodBoolean;
+    changed: z.ZodBoolean;
 }, z.core.$strict>;
-export type SelfServiceRoleGrantOutput = z.infer<typeof SelfServiceRoleGrantOutput>;
-/** Input for `self_service_role_revoke`. */
-export declare const SelfServiceRoleRevokeInput: z.ZodObject<{
-    role: z.ZodString;
-}, z.core.$strict>;
-export type SelfServiceRoleRevokeInput = z.infer<typeof SelfServiceRoleRevokeInput>;
-/**
- * Output for `self_service_role_revoke`. `revoked` is `false` when the
- * caller held no active global permit for the role (idempotent).
- */
-export declare const SelfServiceRoleRevokeOutput: z.ZodObject<{
-    ok: z.ZodLiteral<true>;
-    revoked: z.ZodBoolean;
-}, z.core.$strict>;
-export type SelfServiceRoleRevokeOutput = z.infer<typeof SelfServiceRoleRevokeOutput>;
-export declare const self_service_role_grant_action_spec: {
-    method: string;
-    kind: "request_response";
-    initiator: "frontend";
-    auth: "authenticated";
-    side_effects: true;
-    input: z.ZodObject<{
-        role: z.ZodString;
-    }, z.core.$strict>;
-    output: z.ZodObject<{
-        ok: z.ZodLiteral<true>;
-        granted: z.ZodBoolean;
-        permit_id: z.ZodOptional<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
-    }, z.core.$strict>;
-    async: true;
-    description: string;
-};
-export declare const self_service_role_revoke_action_spec: {
+export type SelfServiceRoleSetOutput = z.infer<typeof SelfServiceRoleSetOutput>;
+export declare const self_service_role_set_action_spec: {
     method: string;
     kind: "request_response";
     initiator: "frontend";
@@ -66,18 +36,20 @@ export declare const self_service_role_revoke_action_spec: {
     side_effects: true;
     input: z.ZodObject<{
         role: z.ZodString;
+        enabled: z.ZodBoolean;
     }, z.core.$strict>;
     output: z.ZodObject<{
         ok: z.ZodLiteral<true>;
-        revoked: z.ZodBoolean;
+        enabled: z.ZodBoolean;
+        changed: z.ZodBoolean;
     }, z.core.$strict>;
     async: true;
     description: string;
 };
 /**
- * All self-service role action specs — a codegen-ready registry. Method
- * names are static, so consumer typed-client codegen picks them up the
- * same way it picks up `account_*_action_specs`.
+ * All self-service role action specs — a codegen-ready registry. Single-element
+ * post-unification, kept for symmetry with the other `all_*_action_specs`
+ * exports so codegen and frontend bundles import the same shape.
  */
-export declare const all_self_service_role_action_specs: Array<RequestResponseActionSpec>;
+export declare const all_self_service_role_action_specs: ReadonlyArray<RequestResponseActionSpec>;
 //# sourceMappingURL=self_service_role_action_specs.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"self_service_role_action_specs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/self_service_role_action_specs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAGtB,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,2BAA2B,CAAC;AAGzE,0FAA0F;AAC1F,eAAO,MAAM,oCAAoC,EAAG,gCAAyC,CAAC;AAE9F,2CAA2C;AAC3C,eAAO,MAAM,yBAAyB;;kBAEpC,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B;;;;kBAIrC,CAAC;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAEpF,4CAA4C;AAC5C,eAAO,MAAM,0BAA0B;;kBAErC,CAAC;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAEpF;;;GAGG;AACH,eAAO,MAAM,2BAA2B;;;kBAGtC,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEtF,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;CAWX,CAAC;AAEtC,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;;;CAWZ,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,EAAE,KAAK,CAAC,yBAAyB,CAG/E,CAAC"}
+{"version":3,"file":"self_service_role_action_specs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/self_service_role_action_specs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,2BAA2B,CAAC;AAGzE,0FAA0F;AAC1F,eAAO,MAAM,oCAAoC,EAAG,gCAAyC,CAAC;AAE9F,yCAAyC;AACzC,eAAO,MAAM,uBAAuB;;;kBAMlC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;;kBAInC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;CAWT,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,EAAE,aAAa,CAAC,yBAAyB,CAEvF,CAAC"}

package/dist/auth/self_service_role_action_specs.js

@@ -1,5 +1,5 @@
 /**
- * Self-service role grant/revoke action specs — schemas, error reasons,
+ * Unified self-service role toggle action spec — schemas, error reasons,
  * and the codegen-ready registry.
  *
  * Client-safe: no query-layer or audit-write imports. Handler factory
@@ -8,64 +8,42 @@
  * @module
  */
 import { z } from 'zod';
-import { Uuid } from '@fuzdev/fuz_util/id.js';
 import { RoleName } from './role_schema.js';
 /** Error reason — caller asked to self-toggle a role outside the configured allowlist. */
 export const ERROR_ROLE_NOT_SELF_SERVICE_ELIGIBLE = 'role_not_self_service_eligible';
-/** Input for `self_service_role_grant`. */
-export const SelfServiceRoleGrantInput = z.strictObject({
-    role: RoleName.meta({ description: 'Role to self-grant. Must be in the configured allowlist.' }),
+/** Input for `self_service_role_set`. */
+export const SelfServiceRoleSetInput = z.strictObject({
+    role: RoleName.meta({ description: 'Role to toggle. Must be in the configured allowlist.' }),
+    enabled: z.boolean().meta({
+        description: 'Desired post-call state. `true` grants if not held; `false` revokes if held. Idempotent in both directions.',
+    }),
 });
 /**
- * Output for `self_service_role_grant`. `granted` is `false` on idempotent
- * re-grant (caller already held the role globally); `permit_id` is set on
- * new grants only.
+ * Output for `self_service_role_set`. `enabled` echoes the post-call state
+ * (always equals the input `enabled` on success). `changed` is `true` only
+ * when the call mutated — re-grants / re-revokes return `false`.
  */
-export const SelfServiceRoleGrantOutput = z.strictObject({
+export const SelfServiceRoleSetOutput = z.strictObject({
     ok: z.literal(true),
-    granted: z.boolean(),
-    permit_id: Uuid.optional(),
+    enabled: z.boolean(),
+    changed: z.boolean(),
 });
-/** Input for `self_service_role_revoke`. */
-export const SelfServiceRoleRevokeInput = z.strictObject({
-    role: RoleName.meta({ description: 'Role to self-revoke. Must be in the configured allowlist.' }),
-});
-/**
- * Output for `self_service_role_revoke`. `revoked` is `false` when the
- * caller held no active global permit for the role (idempotent).
- */
-export const SelfServiceRoleRevokeOutput = z.strictObject({
-    ok: z.literal(true),
-    revoked: z.boolean(),
-});
-export const self_service_role_grant_action_spec = {
-    method: 'self_service_role_grant',
-    kind: 'request_response',
-    initiator: 'frontend',
-    auth: 'authenticated',
-    side_effects: true,
-    input: SelfServiceRoleGrantInput,
-    output: SelfServiceRoleGrantOutput,
-    async: true,
-    description: 'Self-grant an active permit for an allowlisted role. Idempotent — already-granted callers receive `granted: false`.',
-};
-export const self_service_role_revoke_action_spec = {
-    method: 'self_service_role_revoke',
+export const self_service_role_set_action_spec = {
+    method: 'self_service_role_set',
     kind: 'request_response',
     initiator: 'frontend',
     auth: 'authenticated',
     side_effects: true,
-    input: SelfServiceRoleRevokeInput,
-    output: SelfServiceRoleRevokeOutput,
+    input: SelfServiceRoleSetInput,
+    output: SelfServiceRoleSetOutput,
     async: true,
-    description: 'Self-revoke an active global permit for an allowlisted role. Idempotent — callers without an active permit receive `revoked: false`.',
+    description: 'Toggle a self-service role. Idempotent in both directions — `changed: false` when post-call state already matched the request.',
 };
 /**
- * All self-service role action specs — a codegen-ready registry. Method
- * names are static, so consumer typed-client codegen picks them up the
- * same way it picks up `account_*_action_specs`.
+ * All self-service role action specs — a codegen-ready registry. Single-element
+ * post-unification, kept for symmetry with the other `all_*_action_specs`
+ * exports so codegen and frontend bundles import the same shape.
  */
 export const all_self_service_role_action_specs = [
-    self_service_role_grant_action_spec,
-    self_service_role_revoke_action_spec,
+    self_service_role_set_action_spec,
 ];

package/dist/auth/self_service_role_actions.d.ts

@@ -1,11 +1,11 @@
 /**
- * Self-service role grant/revoke RPC actions.
+ * Unified self-service role toggle RPC action.
  *
- * Two static `request_response` actions — `self_service_role_grant` and
- * `self_service_role_revoke` — that take `{role}` as input and toggle a
- * permit on the caller for an allowlisted role. Idempotent in both
- * directions: re-granting an already-held role returns `granted: false`;
- * revoking a role the caller doesn't hold returns `revoked: false`.
+ * One static `request_response` action — `self_service_role_set` — that
+ * takes `{role, enabled}` and toggles a global permit on the caller for an
+ * allowlisted role. Idempotent in both directions: re-enabling an
+ * already-held role returns `changed: false`; disabling a role the caller
+ * doesn't hold returns `changed: false`.
  *
  * The factory takes an `eligible_roles` allowlist (validated against the
  * supplied `roles.role_options` at factory time so typos surface at startup
@@ -19,8 +19,8 @@
  * part of the documented schema surface and is round-trip-validated by
  * `query_audit_log`.
  *
- * Static method names — `role` lives in the input, not the method name —
- * so specs are codegen-compatible (`satisfies RequestResponseActionSpec`)
+ * Static method name — `role` lives in the input, not the method name —
+ * so the spec is codegen-compatible (`satisfies RequestResponseActionSpec`)
  * and the surface stays constant as consumers add eligible roles. Mirrors
  * the existing `permit_offer_create({role})` precedent rather than
  * generating per-role methods.
@@ -57,7 +57,7 @@ export interface SelfServiceRoleActionsOptions {
  */
 export type SelfServiceRoleActionDeps = Pick<RouteFactoryDeps, 'log' | 'on_audit_event' | 'audit_log_config'>;
 /**
- * Build the self-service role grant/revoke RPC actions.
+ * Build the unified self-service role toggle RPC action.
  *
  * @param deps - `SelfServiceRoleActionDeps` slice of `AppDeps` (`log`, `on_audit_event`, optional `audit_log_config`)
  * @param options - eligible-role allowlist plus optional role schema for typo-checking

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

@@ -1 +1 @@
-{"version":3,"file":"self_service_role_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/self_service_role_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAExF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAmBhD,sDAAsD;AACtD,MAAM,WAAW,6BAA6B;IAC7C;;;;OAIG;IACH,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAC3C,gBAAgB,EAChB,KAAK,GAAG,gBAAgB,GAAG,kBAAkB,CAC7C,CAAC;AAOF;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,yBAAyB,EAC/B,SAAS,6BAA6B,KACpC,KAAK,CAAC,SAAS,CAqHjB,CAAC"}
+{"version":3,"file":"self_service_role_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/self_service_role_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAExF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAgBhD,sDAAsD;AACtD,MAAM,WAAW,6BAA6B;IAC7C;;;;OAIG;IACH,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAC3C,gBAAgB,EAChB,KAAK,GAAG,gBAAgB,GAAG,kBAAkB,CAC7C,CAAC;AAOF;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,yBAAyB,EAC/B,SAAS,6BAA6B,KACpC,KAAK,CAAC,SAAS,CA4GjB,CAAC"}

package/dist/auth/self_service_role_actions.js

@@ -1,11 +1,11 @@
 /**
- * Self-service role grant/revoke RPC actions.
+ * Unified self-service role toggle RPC action.
  *
- * Two static `request_response` actions — `self_service_role_grant` and
- * `self_service_role_revoke` — that take `{role}` as input and toggle a
- * permit on the caller for an allowlisted role. Idempotent in both
- * directions: re-granting an already-held role returns `granted: false`;
- * revoking a role the caller doesn't hold returns `revoked: false`.
+ * One static `request_response` action — `self_service_role_set` — that
+ * takes `{role, enabled}` and toggles a global permit on the caller for an
+ * allowlisted role. Idempotent in both directions: re-enabling an
+ * already-held role returns `changed: false`; disabling a role the caller
+ * doesn't hold returns `changed: false`.
  *
  * The factory takes an `eligible_roles` allowlist (validated against the
  * supplied `roles.role_options` at factory time so typos surface at startup
@@ -19,8 +19,8 @@
  * part of the documented schema surface and is round-trip-validated by
  * `query_audit_log`.
  *
- * Static method names — `role` lives in the input, not the method name —
- * so specs are codegen-compatible (`satisfies RequestResponseActionSpec`)
+ * Static method name — `role` lives in the input, not the method name —
+ * so the spec is codegen-compatible (`satisfies RequestResponseActionSpec`)
  * and the surface stays constant as consumers add eligible roles. Mirrors
  * the existing `permit_offer_create({role})` precedent rather than
  * generating per-role methods.
@@ -35,14 +35,14 @@ import { rpc_action } from '../actions/action_rpc.js';
 import { jsonrpc_errors } from '../http/jsonrpc_errors.js';
 import { query_grant_permit, query_permit_find_active_for_actor, query_permit_has_role, query_revoke_permit, } from './permit_queries.js';
 import { audit_log_fire_and_forget } from './audit_log_queries.js';
-import { ERROR_ROLE_NOT_SELF_SERVICE_ELIGIBLE, self_service_role_grant_action_spec, self_service_role_revoke_action_spec, } from './self_service_role_action_specs.js';
+import { ERROR_ROLE_NOT_SELF_SERVICE_ELIGIBLE, self_service_role_set_action_spec, } from './self_service_role_action_specs.js';
 const require_request_auth = (auth) => {
     if (!auth)
         throw new Error('unreachable: action auth guard did not enforce authentication');
     return auth;
 };
 /**
- * Build the self-service role grant/revoke RPC actions.
+ * Build the unified self-service role toggle RPC action.
  *
  * @param deps - `SelfServiceRoleActionDeps` slice of `AppDeps` (`log`, `on_audit_event`, optional `audit_log_config`)
  * @param options - eligible-role allowlist plus optional role schema for typo-checking
@@ -65,45 +65,43 @@ export const create_self_service_role_actions = (deps, options) => {
             });
         }
     };
-    const grant_handler = async (input, ctx) => {
+    const handler = async (input, ctx) => {
         const auth = require_request_auth(ctx.auth);
         reject_if_ineligible(input.role);
-        // Pre-check for idempotent re-grant. `query_grant_permit` is itself
-        // idempotent (returns the existing permit instead of inserting), but
-        // it doesn't signal "already existed" vs "newly inserted" — so we
-        // peek first. The TOCTOU window is benign for self-service: two
-        // concurrent grants both observe "no permit", both call
-        // `query_grant_permit`, and one collapses onto the other inside the
-        // query's `ON CONFLICT DO NOTHING`. Worst case both responses report
-        // `granted: true`; the DB still ends up with exactly one permit.
-        const already = await query_permit_has_role(ctx, auth.actor.id, input.role);
-        if (already) {
-            return { ok: true, granted: false };
+        if (input.enabled) {
+            // Pre-check for idempotent re-grant. `query_grant_permit` is itself
+            // idempotent (returns the existing permit instead of inserting), but
+            // it doesn't signal "already existed" vs "newly inserted" — so we
+            // peek first. The TOCTOU window is benign for self-service: two
+            // concurrent grants both observe "no permit", both call
+            // `query_grant_permit`, and one collapses onto the other inside the
+            // query's `ON CONFLICT DO NOTHING`. Worst case both responses report
+            // `changed: true`; the DB still ends up with exactly one permit.
+            const already = await query_permit_has_role(ctx, auth.actor.id, input.role);
+            if (already) {
+                return { ok: true, enabled: true, changed: false };
+            }
+            const permit = await query_grant_permit(ctx, {
+                actor_id: auth.actor.id,
+                role: input.role,
+                scope_id: null,
+                expires_at: null,
+                granted_by: auth.actor.id,
+            });
+            void audit_log_fire_and_forget(ctx, {
+                event_type: 'permit_grant',
+                actor_id: auth.actor.id,
+                account_id: auth.account.id,
+                ip: ctx.client_ip,
+                metadata: {
+                    role: permit.role,
+                    permit_id: permit.id,
+                    scope_id: permit.scope_id,
+                    self_service: true,
+                },
+            }, deps);
+            return { ok: true, enabled: true, changed: true };
         }
-        const permit = await query_grant_permit(ctx, {
-            actor_id: auth.actor.id,
-            role: input.role,
-            scope_id: null,
-            expires_at: null,
-            granted_by: auth.actor.id,
-        });
-        void audit_log_fire_and_forget(ctx, {
-            event_type: 'permit_grant',
-            actor_id: auth.actor.id,
-            account_id: auth.account.id,
-            ip: ctx.client_ip,
-            metadata: {
-                role: permit.role,
-                permit_id: permit.id,
-                scope_id: permit.scope_id,
-                self_service: true,
-            },
-        }, deps);
-        return { ok: true, granted: true, permit_id: permit.id };
-    };
-    const revoke_handler = async (input, ctx) => {
-        const auth = require_request_auth(ctx.auth);
-        reject_if_ineligible(input.role);
         // Find an active global permit for this (actor, role). No dedicated
         // query exists, but `query_permit_find_active_for_actor` returns the
         // short list of every active permit and we filter in JS — fewer
@@ -111,12 +109,12 @@ export const create_self_service_role_actions = (deps, options) => {
         const active = await query_permit_find_active_for_actor(ctx, auth.actor.id);
         const target = active.find((p) => p.role === input.role && p.scope_id === null);
         if (!target) {
-            return { ok: true, revoked: false };
+            return { ok: true, enabled: false, changed: false };
         }
         const result = await query_revoke_permit(ctx, target.id, auth.actor.id, auth.actor.id);
         if (!result) {
             // Raced with another revoker — treat as already revoked.
-            return { ok: true, revoked: false };
+            return { ok: true, enabled: false, changed: false };
         }
         void audit_log_fire_and_forget(ctx, {
             event_type: 'permit_revoke',
@@ -130,10 +128,7 @@ export const create_self_service_role_actions = (deps, options) => {
                 self_service: true,
             },
         }, deps);
-        return { ok: true, revoked: true };
+        return { ok: true, enabled: false, changed: true };
     };
-    return [
-        rpc_action(self_service_role_grant_action_spec, grant_handler),
-        rpc_action(self_service_role_revoke_action_spec, revoke_handler),
-    ];
+    return [rpc_action(self_service_role_set_action_spec, handler)];
 };

package/dist/auth/standard_action_specs.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Aggregate spec list mirroring `create_standard_rpc_actions` on the backend.
+ *
+ * `create_standard_rpc_actions` (in `./standard_rpc_actions.js`) bundles three
+ * action registries into one mounted RPC surface: admin + permit_offer +
+ * account. Frontends mounting that surface need the matching spec list to
+ * feed `create_rpc_client` so the typed Proxy knows about every standard
+ * method.
+ *
+ * Without this aggregate, every consumer spreads three (or four with
+ * self-service roles) `all_*_action_specs` imports at the typed-client
+ * site, the codegen-sources table, and any other registry construction —
+ * a triplicate that drifts silently on either side.
+ *
+ * Self-service role specs are **not** included — they're opt-in (require
+ * `eligible_roles` configuration) and not bundled into
+ * `create_standard_rpc_actions`. Consumers that mount them spread
+ * `all_self_service_role_action_specs` separately.
+ *
+ * @module
+ */
+import type { RequestResponseActionSpec } from '../actions/action_spec.js';
+/**
+ * Combined spec registry for the standard RPC surface (admin +
+ * permit_offer + account). Symmetric with `create_standard_rpc_actions`.
+ *
+ * Spec count is the sum of the three sub-registries. Adding a method to
+ * any sub-registry surfaces here automatically.
+ */
+export declare const all_standard_action_specs: ReadonlyArray<RequestResponseActionSpec>;
+//# sourceMappingURL=standard_action_specs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"standard_action_specs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/standard_action_specs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,2BAA2B,CAAC;AAKzE;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,EAAE,aAAa,CAAC,yBAAyB,CAI9E,CAAC"}

package/dist/auth/standard_action_specs.js

@@ -0,0 +1,36 @@
+/**
+ * Aggregate spec list mirroring `create_standard_rpc_actions` on the backend.
+ *
+ * `create_standard_rpc_actions` (in `./standard_rpc_actions.js`) bundles three
+ * action registries into one mounted RPC surface: admin + permit_offer +
+ * account. Frontends mounting that surface need the matching spec list to
+ * feed `create_rpc_client` so the typed Proxy knows about every standard
+ * method.
+ *
+ * Without this aggregate, every consumer spreads three (or four with
+ * self-service roles) `all_*_action_specs` imports at the typed-client
+ * site, the codegen-sources table, and any other registry construction —
+ * a triplicate that drifts silently on either side.
+ *
+ * Self-service role specs are **not** included — they're opt-in (require
+ * `eligible_roles` configuration) and not bundled into
+ * `create_standard_rpc_actions`. Consumers that mount them spread
+ * `all_self_service_role_action_specs` separately.
+ *
+ * @module
+ */
+import { all_admin_action_specs } from './admin_action_specs.js';
+import { all_permit_offer_action_specs } from './permit_offer_action_specs.js';
+import { all_account_action_specs } from './account_action_specs.js';
+/**
+ * Combined spec registry for the standard RPC surface (admin +
+ * permit_offer + account). Symmetric with `create_standard_rpc_actions`.
+ *
+ * Spec count is the sum of the three sub-registries. Adding a method to
+ * any sub-registry surfaces here automatically.
+ */
+export const all_standard_action_specs = [
+    ...all_admin_action_specs,
+    ...all_permit_offer_action_specs,
+    ...all_account_action_specs,
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",