@fuzdev/fuz_app 0.50.0 → 0.52.0

package/dist/auth/audit_log_schema.js

@@ -60,32 +60,71 @@ export const AuditOutcome = z.enum(['success', 'failure']);
  * freeze isn't a security boundary.
  */
 export const AUDIT_METADATA_SCHEMAS = Object.freeze({
-    login: z.looseObject({ username: z.string() }).nullable(),
+    login: z
+        .looseObject({
+        username: z.string().meta({ description: 'Username submitted with the login attempt.' }),
+    })
+        .nullable(),
     logout: z.null(),
-    bootstrap: z.looseObject({ error: z.string() }).nullable(),
+    bootstrap: z
+        .looseObject({
+        error: z.string().meta({ description: 'Error message for a failed bootstrap attempt.' }),
+    })
+        .nullable(),
     signup: z.looseObject({
-        username: z.string(),
-        invite_id: Uuid.optional(),
-        open_signup: z.boolean().optional(),
+        username: z.string().meta({ description: 'Username chosen at signup.' }),
+        invite_id: Uuid.optional().meta({
+            description: 'Invite consumed by this signup, when one was matched.',
+        }),
+        open_signup: z.boolean().optional().meta({
+            description: 'True when the signup occurred via the `open_signup` setting (no invite required).',
+        }),
+    }),
+    password_change: z
+        .looseObject({
+        sessions_revoked: z
+            .number()
+            .meta({ description: 'Number of sessions revoked as a side effect of the password change.' }),
+    })
+        .nullable(),
+    session_revoke: z.looseObject({
+        session_id: z.string().meta({ description: 'Blake3 hash identifying the revoked session row.' }),
     }),
-    password_change: z.looseObject({ sessions_revoked: z.number() }).nullable(),
-    session_revoke: z.looseObject({ session_id: z.string() }),
     session_revoke_all: z.looseObject({
         // Omitted on `outcome='failure'` (no revocation attempted — e.g. target
         // account not found); `reason` carries the failure category, and
         // `attempted_account_id` preserves the probed id (the `target_account_id`
         // column is null in that case because it's a FK to `account`).
-        count: z.number().optional(),
-        reason: z.string().optional(),
-        attempted_account_id: Uuid.optional(),
+        count: z.number().optional().meta({
+            description: 'Number of sessions revoked. Omitted on `outcome=failure` because no revocation was attempted.',
+        }),
+        reason: z
+            .string()
+            .optional()
+            .meta({ description: 'Failure category. Set only on `outcome=failure`.' }),
+        attempted_account_id: Uuid.optional().meta({
+            description: 'Probed account id when the target lookup missed (FK constraint forces `target_account_id` to null).',
+        }),
+    }),
+    token_create: z.looseObject({
+        token_id: z.string().meta({ description: 'Public id of the created API token (`tok_…`).' }),
+        name: z.string().meta({ description: 'Operator-supplied label for the token.' }),
+    }),
+    token_revoke: z.looseObject({
+        token_id: z.string().meta({ description: 'Public id of the revoked API token (`tok_…`).' }),
     }),
-    token_create: z.looseObject({ token_id: z.string(), name: z.string() }),
-    token_revoke: z.looseObject({ token_id: z.string() }),
     token_revoke_all: z.looseObject({
         // Same shape as `session_revoke_all` for failures.
-        count: z.number().optional(),
-        reason: z.string().optional(),
-        attempted_account_id: Uuid.optional(),
+        count: z.number().optional().meta({
+            description: 'Number of tokens revoked. Omitted on `outcome=failure` because no revocation was attempted.',
+        }),
+        reason: z
+            .string()
+            .optional()
+            .meta({ description: 'Failure category. Set only on `outcome=failure`.' }),
+        attempted_account_id: Uuid.optional().meta({
+            description: 'Probed account id when the target lookup missed (FK constraint forces `target_account_id` to null).',
+        }),
     }),
     // `permit_id` is optional on `permit_grant` because failed grants
     // (e.g. `web_grantable` denied) never produce a permit row.
@@ -94,72 +133,110 @@ export const AUDIT_METADATA_SCHEMAS = Object.freeze({
     // riding on `z.looseObject` permissiveness so the field is part of
     // the documented schema surface.
     permit_grant: z.looseObject({
-        role: z.string(),
-        permit_id: Uuid.optional(),
-        scope_id: Uuid.nullish(),
-        source_offer_id: Uuid.optional(),
-        self_service: z.boolean().optional(),
+        role: z.string().meta({ description: 'Role being granted.' }),
+        permit_id: Uuid.optional().meta({
+            description: 'Id of the resulting permit row. Omitted when the grant failed (e.g. `web_grantable` denial).',
+        }),
+        scope_id: Uuid.nullish().meta({
+            description: 'Scope of the granted permit; null for global permits.',
+        }),
+        source_offer_id: Uuid.optional().meta({
+            description: 'Offer this grant resolved, when the grant originated from an accepted offer.',
+        }),
+        self_service: z.boolean().optional().meta({
+            description: 'True when the grant came from the self-service role toggle.',
+        }),
     }),
     permit_revoke: z.looseObject({
-        role: z.string(),
-        permit_id: Uuid,
-        scope_id: Uuid.nullish(),
-        reason: z.string().optional(),
-        self_service: z.boolean().optional(),
+        role: z.string().meta({ description: 'Role being revoked.' }),
+        permit_id: Uuid.meta({ description: 'Id of the revoked permit row.' }),
+        scope_id: Uuid.nullish().meta({
+            description: 'Scope of the revoked permit; null for global permits.',
+        }),
+        reason: z
+            .string()
+            .optional()
+            .meta({ description: 'Optional admin-supplied or self-service reason text.' }),
+        self_service: z.boolean().optional().meta({
+            description: 'True when the revoke came from the self-service role toggle.',
+        }),
     }),
     // `offer_id` is optional because failed creates (e.g. `web_grantable`
     // denied, `authorize` callback denied) never produce an offer row.
     permit_offer_create: z.looseObject({
-        offer_id: Uuid.optional(),
-        role: z.string(),
-        scope_id: Uuid.nullish(),
-        to_account_id: Uuid,
+        offer_id: Uuid.optional().meta({
+            description: 'Id of the created offer row. Omitted when the create failed before insert.',
+        }),
+        role: z.string().meta({ description: 'Role being offered.' }),
+        scope_id: Uuid.nullish().meta({
+            description: 'Scope of the offered role; null for global offers.',
+        }),
+        to_account_id: Uuid.meta({ description: 'Account the offer is directed to.' }),
     }),
     // `permit_grant` is emitted alongside on accept — two events per accept by
     // design: offer-lifecycle audit + permit-lifecycle audit.
     permit_offer_accept: z.looseObject({
-        offer_id: Uuid,
-        permit_id: Uuid,
-        role: z.string(),
-        scope_id: Uuid.nullish(),
+        offer_id: Uuid.meta({ description: 'Id of the accepted offer.' }),
+        permit_id: Uuid.meta({ description: 'Id of the resulting permit row.' }),
+        role: z.string().meta({ description: 'Role granted by the offer.' }),
+        scope_id: Uuid.nullish().meta({
+            description: 'Scope of the resulting permit; null for global permits.',
+        }),
     }),
     permit_offer_decline: z.looseObject({
-        offer_id: Uuid,
-        role: z.string(),
-        scope_id: Uuid.nullish(),
-        reason: z.string().optional(),
+        offer_id: Uuid.meta({ description: 'Id of the declined offer.' }),
+        role: z.string().meta({ description: 'Role that was offered.' }),
+        scope_id: Uuid.nullish().meta({
+            description: 'Scope of the offered role; null for global offers.',
+        }),
+        reason: z
+            .string()
+            .optional()
+            .meta({ description: 'Optional decline reason text from the recipient.' }),
     }),
     permit_offer_retract: z.looseObject({
-        offer_id: Uuid,
-        role: z.string(),
-        scope_id: Uuid.nullish(),
+        offer_id: Uuid.meta({ description: 'Id of the retracted offer.' }),
+        role: z.string().meta({ description: 'Role that was offered.' }),
+        scope_id: Uuid.nullish().meta({
+            description: 'Scope of the offered role; null for global offers.',
+        }),
     }),
     permit_offer_expire: z.looseObject({
-        offer_id: Uuid,
-        role: z.string(),
-        scope_id: Uuid.nullish(),
+        offer_id: Uuid.meta({ description: 'Id of the expired offer.' }),
+        role: z.string().meta({ description: 'Role that was offered.' }),
+        scope_id: Uuid.nullish().meta({
+            description: 'Scope of the offered role; null for global offers.',
+        }),
     }),
     // Emitted when an offer is obsoleted by an external event. `reason`
     // distinguishes the trigger; `cause_id` points to the accepted offer
     // (for `sibling_accepted`), the revoked permit (for `permit_revoked`),
     // or the destroyed parent scope row (for `scope_destroyed`).
     permit_offer_supersede: z.looseObject({
-        offer_id: Uuid,
-        role: z.string(),
-        scope_id: Uuid.nullish(),
-        reason: z.enum(['sibling_accepted', 'permit_revoked', 'scope_destroyed']),
-        cause_id: Uuid,
+        offer_id: Uuid.meta({ description: 'Id of the superseded offer.' }),
+        role: z.string().meta({ description: 'Role that was offered.' }),
+        scope_id: Uuid.nullish().meta({
+            description: 'Scope of the offered role; null for global offers.',
+        }),
+        reason: z.enum(['sibling_accepted', 'permit_revoked', 'scope_destroyed']).meta({
+            description: 'Trigger that obsoleted the offer: a sibling offer was accepted, the resulting permit was revoked, or the parent scope row was destroyed.',
+        }),
+        cause_id: Uuid.meta({
+            description: 'Row that caused the supersede: accepted offer (`sibling_accepted`), revoked permit (`permit_revoked`), or destroyed parent scope row (`scope_destroyed`).',
+        }),
     }),
     invite_create: z.looseObject({
-        invite_id: Uuid,
-        email: z.string().nullable(),
-        username: z.string().nullable(),
+        invite_id: Uuid.meta({ description: 'Id of the created invite.' }),
+        email: z.string().nullable().meta({ description: 'Invited email address; null when not set.' }),
+        username: z.string().nullable().meta({ description: 'Invited username; null when not set.' }),
+    }),
+    invite_delete: z.looseObject({
+        invite_id: Uuid.meta({ description: 'Id of the deleted invite.' }),
     }),
-    invite_delete: z.looseObject({ invite_id: Uuid }),
     app_settings_update: z.looseObject({
-        setting: z.string(),
-        old_value: z.unknown(),
-        new_value: z.unknown(),
+        setting: z.string().meta({ description: 'Name of the setting that changed.' }),
+        old_value: z.unknown().meta({ description: 'Setting value before the update.' }),
+        new_value: z.unknown().meta({ description: 'Setting value after the update.' }),
     }),
 });
 /**
@@ -184,6 +261,8 @@ export const BUILTIN_AUDIT_LOG_CONFIG = Object.freeze({
  * Call once at startup; pass the result to consumer-emitted
  * `audit_log_fire_and_forget` calls. Builtin handlers omit the argument and
  * pick up `BUILTIN_AUDIT_LOG_CONFIG`.
+ *
+ * @throws Error when an `extra_events` key collides with a builtin event type or fails `AuditEventTypeName` format validation
  */
 export const create_audit_log_config = (options) => {
     const extras = options?.extra_events;

package/dist/auth/bearer_auth.d.ts

@@ -37,6 +37,8 @@ import { type RateLimiter } from '../rate_limiter.js';
  * @param deps - query dependencies (pool-level db for middleware)
  * @param ip_rate_limiter - per-IP rate limiter for bearer token attempts (null to disable)
  * @param log - the logger instance
+ * @mutates Hono context - sets `REQUEST_CONTEXT_KEY`, `CREDENTIAL_TYPE_KEY`, and `AUTH_API_TOKEN_ID_KEY` on success
+ * @mutates `ip_rate_limiter` - records on attempt; resets on a valid token
  */
 export declare const create_bearer_auth_middleware: (deps: QueryDeps, ip_rate_limiter: RateLimiter | null, log: Logger) => MiddlewareHandler;
 //# sourceMappingURL=bearer_auth.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"bearer_auth.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/bearer_auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAC5C,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAKpD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAA+B,KAAK,WAAW,EAAC,MAAM,oBAAoB,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,iBAAiB,WAAW,GAAG,IAAI,EACnC,KAAK,MAAM,KACT,iBAsFF,CAAC"}
+{"version":3,"file":"bearer_auth.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/bearer_auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAC5C,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAKpD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAA+B,KAAK,WAAW,EAAC,MAAM,oBAAoB,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,iBAAiB,WAAW,GAAG,IAAI,EACnC,KAAK,MAAM,KACT,iBAsFF,CAAC"}

package/dist/auth/bearer_auth.js

@@ -38,6 +38,8 @@ import { rate_limit_exceeded_response } from '../rate_limiter.js';
  * @param deps - query dependencies (pool-level db for middleware)
  * @param ip_rate_limiter - per-IP rate limiter for bearer token attempts (null to disable)
  * @param log - the logger instance
+ * @mutates Hono context - sets `REQUEST_CONTEXT_KEY`, `CREDENTIAL_TYPE_KEY`, and `AUTH_API_TOKEN_ID_KEY` on success
+ * @mutates `ip_rate_limiter` - records on attempt; resets on a valid token
  */
 export const create_bearer_auth_middleware = (deps, ip_rate_limiter, log) => {
     return async (c, next) => {

package/dist/auth/bootstrap_account.d.ts

@@ -77,6 +77,9 @@ export interface BootstrapAccountDeps {
  * @param provided_token - the bootstrap token from the user
  * @param input - username and password
  * @returns the created account, actor, and permits — or a bootstrap failure
+ * @mutates `bootstrap_lock` row - flips `bootstrapped` to `true` atomically
+ * @mutates `account` / `actor` / `permit` tables - inserts the bootstrap account, actor, and the keeper + admin permits
+ * @mutates filesystem - deletes the bootstrap token file after commit (reported via `token_file_deleted`)
  */
 export declare const bootstrap_account: (deps: BootstrapAccountDeps, provided_token: string, input: BootstrapAccountInput) => Promise<BootstrapAccountResult>;
 //# sourceMappingURL=bootstrap_account.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"bootstrap_account.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/bootstrap_account.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,eAAe,CAAC;AACpD,OAAO,EACN,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAC,MAAM,qBAAqB,CAAC;AAGhE,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AAEpC,gDAAgD;AAChD,MAAM,WAAW,qBAAqB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,6DAA6D;AAC7D,MAAM,WAAW,uBAAuB;IACvC,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CAAC;IACzC,wFAAwF;IACxF,kBAAkB,EAAE,OAAO,CAAC;CAC5B;AAED,gCAAgC;AAChC,MAAM,MAAM,uBAAuB,GAChC;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,0BAA0B,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAC,GAClE;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,wBAAwB,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAC,GAChE;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,mBAAmB,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAC,CAAC;AAE/D,qFAAqF;AACrF,MAAM,MAAM,sBAAsB,GAAG,uBAAuB,GAAG,uBAAuB,CAAC;AAEvF;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,EAAE,EAAE,EAAE,CAAC;IACP,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,qBAAqB;IACrB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,6EAA6E;IAC7E,QAAQ,EAAE,IAAI,CAAC,gBAAgB,EAAE,eAAe,CAAC,CAAC;IAClD,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,iBAAiB,GAC7B,MAAM,oBAAoB,EAC1B,gBAAgB,MAAM,EACtB,OAAO,qBAAqB,KAC1B,OAAO,CAAC,sBAAsB,CA4EhC,CAAC"}
+{"version":3,"file":"bootstrap_account.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/bootstrap_account.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,eAAe,CAAC;AACpD,OAAO,EACN,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAC,MAAM,qBAAqB,CAAC;AAGhE,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AAEpC,gDAAgD;AAChD,MAAM,WAAW,qBAAqB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,6DAA6D;AAC7D,MAAM,WAAW,uBAAuB;IACvC,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CAAC;IACzC,wFAAwF;IACxF,kBAAkB,EAAE,OAAO,CAAC;CAC5B;AAED,gCAAgC;AAChC,MAAM,MAAM,uBAAuB,GAChC;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,0BAA0B,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAC,GAClE;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,wBAAwB,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAC,GAChE;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,mBAAmB,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAC,CAAC;AAE/D,qFAAqF;AACrF,MAAM,MAAM,sBAAsB,GAAG,uBAAuB,GAAG,uBAAuB,CAAC;AAEvF;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,EAAE,EAAE,EAAE,CAAC;IACP,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,qBAAqB;IACrB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,6EAA6E;IAC7E,QAAQ,EAAE,IAAI,CAAC,gBAAgB,EAAE,eAAe,CAAC,CAAC;IAClD,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,iBAAiB,GAC7B,MAAM,oBAAoB,EAC1B,gBAAgB,MAAM,EACtB,OAAO,qBAAqB,KAC1B,OAAO,CAAC,sBAAsB,CA4EhC,CAAC"}

package/dist/auth/bootstrap_account.js

@@ -28,6 +28,9 @@ import { query_grant_permit } from './permit_queries.js';
  * @param provided_token - the bootstrap token from the user
  * @param input - username and password
  * @returns the created account, actor, and permits — or a bootstrap failure
+ * @mutates `bootstrap_lock` row - flips `bootstrapped` to `true` atomically
+ * @mutates `account` / `actor` / `permit` tables - inserts the bootstrap account, actor, and the keeper + admin permits
+ * @mutates filesystem - deletes the bootstrap token file after commit (reported via `token_file_deleted`)
  */
 export const bootstrap_account = async (deps, provided_token, input) => {
     const { db, token_path, read_text_file, delete_file, password, log } = deps;

package/dist/auth/cleanup.d.ts

@@ -55,6 +55,8 @@ export interface AuthCleanupResult {
  * expiry, and accepted rows are the provenance for the resulting permit
  * (deleting expired rows would not threaten that, but keeping them uniform
  * with the retention policy for terminal rows is simpler).
+ *
+ * @mutates `audit_log` table - inserts one `permit_offer_expire` row per swept offer
  */
 export declare const cleanup_expired_permit_offers: (deps: AuthCleanupDeps) => Promise<number>;
 /**
@@ -66,6 +68,10 @@ export declare const cleanup_expired_permit_offers: (deps: AuthCleanupDeps) => P
  * re-thrown so the caller's scheduler can log/alert; use the per-task
  * helpers (`query_session_cleanup_expired`, `cleanup_expired_permit_offers`)
  * directly if you need finer error isolation.
+ *
+ * @mutates `auth_session` table - deletes expired sessions
+ * @mutates `audit_log` table - emits `permit_offer_expire` rows for expired offers
+ * @throws Error re-thrown from any sweep that fails (no per-sweep isolation here)
  */
 export declare const run_auth_cleanup: (deps: AuthCleanupDeps) => Promise<AuthCleanupResult>;
 //# sourceMappingURL=cleanup.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"cleanup.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/cleanup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAInD,OAAO,KAAK,EAAC,cAAc,EAAE,aAAa,EAAC,MAAM,uBAAuB,CAAC;AAEzE,4CAA4C;AAC5C,MAAM,WAAW,eAAgB,SAAQ,SAAS;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACzD;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,cAAc,CAAC;CAClC;AAED,oCAAoC;AACpC,MAAM,WAAW,iBAAiB;IACjC,8CAA8C;IAC9C,gBAAgB,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,cAAc,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,6BAA6B,GAAU,MAAM,eAAe,KAAG,OAAO,CAAC,MAAM,CAiCzF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,GAAU,MAAM,eAAe,KAAG,OAAO,CAAC,iBAAiB,CAIvF,CAAC"}
+{"version":3,"file":"cleanup.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/cleanup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAInD,OAAO,KAAK,EAAC,cAAc,EAAE,aAAa,EAAC,MAAM,uBAAuB,CAAC;AAEzE,4CAA4C;AAC5C,MAAM,WAAW,eAAgB,SAAQ,SAAS;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACzD;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,cAAc,CAAC;CAClC;AAED,oCAAoC;AACpC,MAAM,WAAW,iBAAiB;IACjC,8CAA8C;IAC9C,gBAAgB,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,cAAc,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,6BAA6B,GAAU,MAAM,eAAe,KAAG,OAAO,CAAC,MAAM,CAiCzF,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,GAAU,MAAM,eAAe,KAAG,OAAO,CAAC,iBAAiB,CAIvF,CAAC"}

package/dist/auth/cleanup.js

@@ -30,6 +30,8 @@ import { query_audit_log } from './audit_log_queries.js';
  * expiry, and accepted rows are the provenance for the resulting permit
  * (deleting expired rows would not threaten that, but keeping them uniform
  * with the retention policy for terminal rows is simpler).
+ *
+ * @mutates `audit_log` table - inserts one `permit_offer_expire` row per swept offer
  */
 export const cleanup_expired_permit_offers = async (deps) => {
     const expired = await query_permit_offer_sweep_expired(deps);
@@ -72,6 +74,10 @@ export const cleanup_expired_permit_offers = async (deps) => {
  * re-thrown so the caller's scheduler can log/alert; use the per-task
  * helpers (`query_session_cleanup_expired`, `cleanup_expired_permit_offers`)
  * directly if you need finer error isolation.
+ *
+ * @mutates `auth_session` table - deletes expired sessions
+ * @mutates `audit_log` table - emits `permit_offer_expire` rows for expired offers
+ * @throws Error re-thrown from any sweep that fails (no per-sweep isolation here)
  */
 export const run_auth_cleanup = async (deps) => {
     const expired_sessions = await query_session_cleanup_expired(deps);

package/dist/auth/daemon_token.d.ts

@@ -3,7 +3,7 @@
  *
  * Pure auth operations with no I/O or state management.
  * The middleware, rotation, and persistence logic lives in
- * `daemon_token_middleware.ts`.
+ * `auth/daemon_token_middleware.ts`.
  *
  * @module
  */

package/dist/auth/daemon_token.js

@@ -3,7 +3,7 @@
  *
  * Pure auth operations with no I/O or state management.
  * The middleware, rotation, and persistence logic lives in
- * `daemon_token_middleware.ts`.
+ * `auth/daemon_token_middleware.ts`.
  *
  * @module
  */

package/dist/auth/daemon_token_middleware.d.ts

@@ -4,7 +4,7 @@
  * Manages the lifecycle of filesystem-resident daemon tokens: writing to disk,
  * rotation on an interval, and HTTP middleware for authentication.
  *
- * Pure token primitives (schema, generation, validation) live in `daemon_token.ts`.
+ * Pure token primitives (schema, generation, validation) live in `auth/daemon_token.ts`.
  * See docs/identity.md for design rationale.
  *
  * @module
@@ -37,6 +37,7 @@ export declare const get_daemon_token_path: (runtime: Pick<EnvDeps, "env_get">,
  * @param runtime - runtime with file write capabilities
  * @param token_path - path to write the token
  * @param token - the raw token string
+ * @mutates filesystem - writes `token_path` atomically and `chmod 0600` when supported
  */
 export declare const write_daemon_token: (runtime: DaemonTokenWriteDeps, token_path: string, token: string) => Promise<void>;
 /**
@@ -74,6 +75,8 @@ export interface DaemonTokenRotation {
  * @param options - rotation configuration
  * @param log - the logger instance
  * @returns rotation state and stop function
+ * @mutates filesystem - writes the token file on each rotation; `stop` removes it
+ * @throws Error if `$HOME` is not set so the daemon token path cannot be resolved
  */
 export declare const start_daemon_token_rotation: (runtime: DaemonTokenWriteDeps & FsRemoveDeps, deps: QueryDeps, options: DaemonTokenRotationOptions, log: Logger) => Promise<DaemonTokenRotation>;
 /**
@@ -88,6 +91,7 @@ export declare const start_daemon_token_rotation: (runtime: DaemonTokenWriteDeps
  *
  * @param state - the daemon token runtime state
  * @param deps - query dependencies (pool-level db for middleware)
+ * @mutates Hono context - sets `REQUEST_CONTEXT_KEY`, `CREDENTIAL_TYPE_KEY`, and `AUTH_API_TOKEN_ID_KEY` on a valid token
  */
 export declare const create_daemon_token_middleware: (state: DaemonTokenState, deps: QueryDeps) => MiddlewareHandler;
 //# sourceMappingURL=daemon_token_middleware.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"daemon_token_middleware.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/daemon_token_middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAC5C,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAAC,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,KAAK,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAWrF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAKN,KAAK,gBAAgB,EACrB,MAAM,mBAAmB,CAAC;AAE3B,8DAA8D;AAC9D,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD,iDAAiD;AACjD,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,GAC1D,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,iBAAiB,GAAG,QAAQ,CAAC,GAAG;IAC3D,6FAA6F;IAC7F,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GACjC,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,MAAM,MAAM,KACV,MAAM,GAAG,IAGX,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAC9B,SAAS,oBAAoB,EAC7B,YAAY,MAAM,EAClB,OAAO,MAAM,KACX,OAAO,CAAC,IAAI,CAKd,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAEtF,CAAC;AAEF,yCAAyC;AACzC,MAAM,WAAW,0BAA0B;IAC1C,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,gDAAgD;AAChD,MAAM,WAAW,mBAAmB;IACnC,2EAA2E;IAC3E,KAAK,EAAE,gBAAgB,CAAC;IACxB,kGAAkG;IAClG,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,2BAA2B,GACvC,SAAS,oBAAoB,GAAG,YAAY,EAC5C,MAAM,SAAS,EACf,SAAS,0BAA0B,EACnC,KAAK,MAAM,KACT,OAAO,CAAC,mBAAmB,CAwD7B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,8BAA8B,GAC1C,OAAO,gBAAgB,EACvB,MAAM,SAAS,KACb,iBAqCF,CAAC"}
+{"version":3,"file":"daemon_token_middleware.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/daemon_token_middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAC5C,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAAC,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,KAAK,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAWrF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAKN,KAAK,gBAAgB,EACrB,MAAM,mBAAmB,CAAC;AAE3B,8DAA8D;AAC9D,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD,iDAAiD;AACjD,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,GAC1D,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,iBAAiB,GAAG,QAAQ,CAAC,GAAG;IAC3D,6FAA6F;IAC7F,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GACjC,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,MAAM,MAAM,KACV,MAAM,GAAG,IAGX,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAC9B,SAAS,oBAAoB,EAC7B,YAAY,MAAM,EAClB,OAAO,MAAM,KACX,OAAO,CAAC,IAAI,CAKd,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAEtF,CAAC;AAEF,yCAAyC;AACzC,MAAM,WAAW,0BAA0B;IAC1C,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,gDAAgD;AAChD,MAAM,WAAW,mBAAmB;IACnC,2EAA2E;IAC3E,KAAK,EAAE,gBAAgB,CAAC;IACxB,kGAAkG;IAClG,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,2BAA2B,GACvC,SAAS,oBAAoB,GAAG,YAAY,EAC5C,MAAM,SAAS,EACf,SAAS,0BAA0B,EACnC,KAAK,MAAM,KACT,OAAO,CAAC,mBAAmB,CAwD7B,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,8BAA8B,GAC1C,OAAO,gBAAgB,EACvB,MAAM,SAAS,KACb,iBAqCF,CAAC"}

package/dist/auth/daemon_token_middleware.js

@@ -4,7 +4,7 @@
  * Manages the lifecycle of filesystem-resident daemon tokens: writing to disk,
  * rotation on an interval, and HTTP middleware for authentication.
  *
- * Pure token primitives (schema, generation, validation) live in `daemon_token.ts`.
+ * Pure token primitives (schema, generation, validation) live in `auth/daemon_token.ts`.
  * See docs/identity.md for design rationale.
  *
  * @module
@@ -39,6 +39,7 @@ export const get_daemon_token_path = (runtime, name) => {
  * @param runtime - runtime with file write capabilities
  * @param token_path - path to write the token
  * @param token - the raw token string
+ * @mutates filesystem - writes `token_path` atomically and `chmod 0600` when supported
  */
 export const write_daemon_token = async (runtime, token_path, token) => {
     await write_file_atomic(runtime, token_path, token + '\n');
@@ -69,6 +70,8 @@ export const resolve_keeper_account_id = async (deps) => {
  * @param options - rotation configuration
  * @param log - the logger instance
  * @returns rotation state and stop function
+ * @mutates filesystem - writes the token file on each rotation; `stop` removes it
+ * @throws Error if `$HOME` is not set so the daemon token path cannot be resolved
  */
 export const start_daemon_token_rotation = async (runtime, deps, options, log) => {
     const { app_name, rotation_interval_ms = DEFAULT_ROTATION_INTERVAL_MS } = options;
@@ -134,6 +137,7 @@ export const start_daemon_token_rotation = async (runtime, deps, options, log) =
  *
  * @param state - the daemon token runtime state
  * @param deps - query dependencies (pool-level db for middleware)
+ * @mutates Hono context - sets `REQUEST_CONTEXT_KEY`, `CREDENTIAL_TYPE_KEY`, and `AUTH_API_TOKEN_ID_KEY` on a valid token
  */
 export const create_daemon_token_middleware = (state, deps) => {
     return async (c, next) => {

package/dist/auth/ddl.d.ts

@@ -1,7 +1,7 @@
 /**
  * Auth table DDL — CREATE TABLE, index, and seed statements.
  *
- * Consumed by `migrations.ts`. Separated from `account_schema.ts`
+ * Consumed by `auth/migrations.ts`. Separated from `auth/account_schema.ts`
  * to isolate DDL concerns from runtime types.
  *
  * @module

package/dist/auth/ddl.js

@@ -1,7 +1,7 @@
 /**
  * Auth table DDL — CREATE TABLE, index, and seed statements.
  *
- * Consumed by `migrations.ts`. Separated from `account_schema.ts`
+ * Consumed by `auth/migrations.ts`. Separated from `auth/account_schema.ts`
  * to isolate DDL concerns from runtime types.
  *
  * @module

package/dist/auth/invite_queries.d.ts

@@ -14,6 +14,8 @@ import type { Invite, CreateInviteInput, InviteWithUsernamesJson } from './invit
  * @param deps - query dependencies
  * @param input - the invite fields
  * @returns the created invite
+ * @mutates `invite` table - inserts the new row
+ * @throws Error if the INSERT does not return a row (failed `assert_row` invariant)
  */
 export declare const query_create_invite: (deps: QueryDeps, input: CreateInviteInput) => Promise<Invite>;
 /**
@@ -44,6 +46,7 @@ export declare const query_invite_find_unclaimed_match: (deps: QueryDeps, email:
  * @param invite_id - the invite to claim
  * @param account_id - the account claiming the invite
  * @returns true if the invite was claimed, false if already claimed or not found
+ * @mutates `invite` row - sets `claimed_by` and `claimed_at` when still unclaimed
  */
 export declare const query_invite_claim: (deps: QueryDeps, invite_id: string, account_id: string) => Promise<boolean>;
 /**
@@ -63,6 +66,7 @@ export declare const query_invite_list_all_with_usernames: (deps: QueryDeps) =>
  * @param deps - query dependencies
  * @param id - the invite id
  * @returns true if deleted, false if not found or already claimed
+ * @mutates `invite` table - deletes the row when still unclaimed
  */
 export declare const query_invite_delete_unclaimed: (deps: QueryDeps, id: string) => Promise<boolean>;
 //# sourceMappingURL=invite_queries.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"invite_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/invite_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAC,MAAM,EAAE,iBAAiB,EAAE,uBAAuB,EAAC,MAAM,oBAAoB,CAAC;AAE3F;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,OAAO,iBAAiB,KACtB,OAAO,CAAC,MAAM,CAQhB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oCAAoC,GAChD,MAAM,SAAS,EACf,OAAO,MAAM,KACX,OAAO,CAAC,MAAM,GAAG,SAAS,CAK5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uCAAuC,GACnD,MAAM,SAAS,EACf,UAAU,MAAM,KACd,OAAO,CAAC,MAAM,GAAG,SAAS,CAK5B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,GAC7C,MAAM,SAAS,EACf,OAAO,MAAM,GAAG,IAAI,EACpB,UAAU,MAAM,KACd,OAAO,CAAC,MAAM,GAAG,SAAS,CAe5B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAC9B,MAAM,SAAS,EACf,WAAW,MAAM,EACjB,YAAY,MAAM,KAChB,OAAO,CAAC,OAAO,CAQjB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAElF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oCAAoC,GAChD,MAAM,SAAS,KACb,OAAO,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAUxC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,IAAI,MAAM,KACR,OAAO,CAAC,OAAO,CAMjB,CAAC"}
+{"version":3,"file":"invite_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/invite_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAC,MAAM,EAAE,iBAAiB,EAAE,uBAAuB,EAAC,MAAM,oBAAoB,CAAC;AAE3F;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,OAAO,iBAAiB,KACtB,OAAO,CAAC,MAAM,CAQhB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oCAAoC,GAChD,MAAM,SAAS,EACf,OAAO,MAAM,KACX,OAAO,CAAC,MAAM,GAAG,SAAS,CAK5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uCAAuC,GACnD,MAAM,SAAS,EACf,UAAU,MAAM,KACd,OAAO,CAAC,MAAM,GAAG,SAAS,CAK5B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,GAC7C,MAAM,SAAS,EACf,OAAO,MAAM,GAAG,IAAI,EACpB,UAAU,MAAM,KACd,OAAO,CAAC,MAAM,GAAG,SAAS,CAe5B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAC9B,MAAM,SAAS,EACf,WAAW,MAAM,EACjB,YAAY,MAAM,KAChB,OAAO,CAAC,OAAO,CAQjB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAElF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oCAAoC,GAChD,MAAM,SAAS,KACb,OAAO,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAUxC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,IAAI,MAAM,KACR,OAAO,CAAC,OAAO,CAMjB,CAAC"}

package/dist/auth/invite_queries.js

@@ -13,6 +13,8 @@ import { assert_row } from '../db/assert_row.js';
  * @param deps - query dependencies
  * @param input - the invite fields
  * @returns the created invite
+ * @mutates `invite` table - inserts the new row
+ * @throws Error if the INSERT does not return a row (failed `assert_row` invariant)
  */
 export const query_create_invite = async (deps, input) => {
     const row = await deps.db.query_one(`INSERT INTO invite (email, username, created_by)
@@ -64,6 +66,7 @@ export const query_invite_find_unclaimed_match = async (deps, email, username) =
  * @param invite_id - the invite to claim
  * @param account_id - the account claiming the invite
  * @returns true if the invite was claimed, false if already claimed or not found
+ * @mutates `invite` row - sets `claimed_by` and `claimed_at` when still unclaimed
  */
 export const query_invite_claim = async (deps, invite_id, account_id) => {
     const rows = await deps.db.query(`UPDATE invite SET claimed_by = $1, claimed_at = NOW()
@@ -98,6 +101,7 @@ export const query_invite_list_all_with_usernames = async (deps) => {
  * @param deps - query dependencies
  * @param id - the invite id
  * @returns true if deleted, false if not found or already claimed
+ * @mutates `invite` table - deletes the row when still unclaimed
  */
 export const query_invite_delete_unclaimed = async (deps, id) => {
     const rows = await deps.db.query(`DELETE FROM invite WHERE id = $1 AND claimed_at IS NULL RETURNING id`, [id]);

package/dist/auth/password.d.ts

@@ -2,7 +2,7 @@
  * Password hashing type definitions.
  *
  * Defines the `PasswordHashDeps` injectable interface and `PASSWORD_LENGTH_MIN`.
- * Concrete Argon2id implementation lives in `password_argon2.ts`.
+ * Concrete Argon2id implementation lives in `auth/password_argon2.ts`.
  *
  * @module
  */

package/dist/auth/password.js

@@ -2,7 +2,7 @@
  * Password hashing type definitions.
  *
  * Defines the `PasswordHashDeps` injectable interface and `PASSWORD_LENGTH_MIN`.
- * Concrete Argon2id implementation lives in `password_argon2.ts`.
+ * Concrete Argon2id implementation lives in `auth/password_argon2.ts`.
  *
  * @module
  */

package/dist/auth/permit_offer_action_specs.d.ts

@@ -209,6 +209,7 @@ export declare const permit_offer_create_action_spec: {
     }, z.core.$strict>;
     async: true;
     description: string;
+    error_reasons: ("offer_self_target" | "offer_role_not_grantable" | "offer_not_authorized")[];
 };
 export declare const permit_offer_accept_action_spec: {
     method: string;
@@ -241,6 +242,7 @@ export declare const permit_offer_accept_action_spec: {
     }, z.core.$strict>;
     async: true;
     description: string;
+    error_reasons: ("offer_terminal" | "offer_expired" | "offer_not_found")[];
 };
 export declare const permit_offer_decline_action_spec: {
     method: string;
@@ -257,6 +259,7 @@ export declare const permit_offer_decline_action_spec: {
     }, z.core.$strict>;
     async: true;
     description: string;
+    error_reasons: ("offer_terminal" | "offer_not_found")[];
 };
 export declare const permit_offer_retract_action_spec: {
     method: string;
@@ -272,6 +275,7 @@ export declare const permit_offer_retract_action_spec: {
     }, z.core.$strict>;
     async: true;
     description: string;
+    error_reasons: ("offer_terminal" | "offer_not_found")[];
 };
 export declare const permit_offer_list_action_spec: {
     method: string;
@@ -354,6 +358,7 @@ export declare const permit_revoke_action_spec: {
     }, z.core.$strict>;
     async: true;
     description: string;
+    error_reasons: ("account_not_found" | "role_not_web_grantable" | "permit_not_found")[];
 };
 /**
  * All permit-offer action specs — a codegen-ready registry. Consumers spread

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

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