@fuzdev/fuz_app 0.1.0

package/dist/auth/middleware.js

@@ -0,0 +1,64 @@
+/**
+ * Auth middleware stack factory.
+ *
+ * Creates the standard middleware layers (origin, session, request_context,
+ * bearer_auth, optional daemon_token) from configuration.
+ *
+ * @module
+ */
+import { ApiError, RateLimitError } from '../http/error_schemas.js';
+/**
+ * Create the auth middleware stack.
+ *
+ * Returns `[origin, session, request_context, bearer_auth]` middleware specs
+ * for the given path pattern. When `daemon_token_state` is provided, appends
+ * a 5th `daemon_token` layer. Apps can append extra entries for non-standard
+ * paths (e.g., tx's `/tx` binary endpoint).
+ *
+ * @param deps - stateless capabilities (keyring, db)
+ * @param options - middleware configuration (allowed_origins, session_options, path, daemon_token_state)
+ * @returns the middleware spec array
+ */
+export const create_auth_middleware_specs = async (deps, options) => {
+    const { keyring, db } = deps;
+    const { allowed_origins, session_options, path = '/api/*', daemon_token_state, bearer_ip_rate_limiter, } = options;
+    const query_deps = { db };
+    // Dynamic imports to avoid pulling heavy dependencies into this module
+    // when consumers only need types (MiddlewareSpec, RouteSpec, etc.)
+    const [{ verify_request_source }, { create_session_middleware }, { create_request_context_middleware }, { create_bearer_auth_middleware },] = await Promise.all([
+        import('../http/origin.js'),
+        import('./session_middleware.js'),
+        import('./request_context.js'),
+        import('./bearer_auth.js'),
+    ]);
+    const session_middleware = create_session_middleware(keyring, session_options);
+    const request_context_middleware = create_request_context_middleware(query_deps, deps.log);
+    const bearer_auth_middleware = create_bearer_auth_middleware(query_deps, bearer_ip_rate_limiter, deps.log);
+    const specs = [
+        {
+            name: 'origin',
+            path,
+            handler: verify_request_source(allowed_origins),
+            errors: { 403: ApiError },
+        },
+        { name: 'session', path, handler: session_middleware },
+        { name: 'request_context', path, handler: request_context_middleware },
+        {
+            name: 'bearer_auth',
+            path,
+            handler: bearer_auth_middleware,
+            errors: { 401: ApiError, 403: ApiError, 429: RateLimitError },
+        },
+    ];
+    if (daemon_token_state) {
+        const { create_daemon_token_middleware } = await import('./daemon_token_middleware.js');
+        const daemon_token_middleware = create_daemon_token_middleware(daemon_token_state, query_deps);
+        specs.push({
+            name: 'daemon_token',
+            path,
+            handler: daemon_token_middleware,
+            errors: { 401: ApiError, 500: ApiError, 503: ApiError },
+        });
+    }
+    return specs;
+};

package/dist/auth/migrations.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Auth schema migrations.
+ *
+ * Single v0 migration for the fuz identity system tables.
+ * Consumed by `run_migrations` with namespace `'fuz_auth'`.
+ *
+ * Collapsed to a single v0 for the 0.1.0 release — no production databases
+ * exist, so the prior v0–v6 development iterations are consolidated.
+ * Post-0.1.0, each new migration appends as v1, v2, etc.
+ *
+ * To add a migration, append a new entry to `AUTH_MIGRATIONS`:
+ *
+ * ```ts
+ * // v1: add display_name to account
+ * {
+ *   name: 'account_display_name',
+ *   up: async (db) => {
+ *     await db.query('ALTER TABLE account ADD COLUMN display_name TEXT');
+ *   },
+ * },
+ * ```
+ *
+ * Migrations are forward-only (no down). Use `IF NOT EXISTS` / `IF EXISTS`
+ * for DDL safety. Named migrations (`{name, up}`) are preferred for
+ * debuggability — the name appears in error messages on failure.
+ *
+ * @module
+ */
+import type { Migration, MigrationNamespace } from '../db/migrate.js';
+/** Namespace identifier for fuz_app auth migrations. */
+export declare const AUTH_MIGRATION_NAMESPACE = "fuz_auth";
+/**
+ * Auth schema migrations in order.
+ *
+ * - v0: Full auth schema — account (with email_verified), actor, permit,
+ *   auth_session, api_token, audit_log (with seq), bootstrap_lock, invite,
+ *   app_settings, plus all indexes and seeds.
+ */
+export declare const AUTH_MIGRATIONS: Array<Migration>;
+/** Pre-composed migration namespace for auth tables. */
+export declare const AUTH_MIGRATION_NS: MigrationNamespace;
+//# sourceMappingURL=migrations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAuBH,OAAO,KAAK,EAAC,SAAS,EAAE,kBAAkB,EAAC,MAAM,kBAAkB,CAAC;AAEpE,wDAAwD;AACxD,eAAO,MAAM,wBAAwB,aAAa,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,SAAS,CAkC5C,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,EAAE,kBAG/B,CAAC"}

package/dist/auth/migrations.js

@@ -0,0 +1,79 @@
+/**
+ * Auth schema migrations.
+ *
+ * Single v0 migration for the fuz identity system tables.
+ * Consumed by `run_migrations` with namespace `'fuz_auth'`.
+ *
+ * Collapsed to a single v0 for the 0.1.0 release — no production databases
+ * exist, so the prior v0–v6 development iterations are consolidated.
+ * Post-0.1.0, each new migration appends as v1, v2, etc.
+ *
+ * To add a migration, append a new entry to `AUTH_MIGRATIONS`:
+ *
+ * ```ts
+ * // v1: add display_name to account
+ * {
+ *   name: 'account_display_name',
+ *   up: async (db) => {
+ *     await db.query('ALTER TABLE account ADD COLUMN display_name TEXT');
+ *   },
+ * },
+ * ```
+ *
+ * Migrations are forward-only (no down). Use `IF NOT EXISTS` / `IF EXISTS`
+ * for DDL safety. Named migrations (`{name, up}`) are preferred for
+ * debuggability — the name appears in error messages on failure.
+ *
+ * @module
+ */
+import { ACCOUNT_SCHEMA, ACCOUNT_EMAIL_INDEX, ACCOUNT_USERNAME_CI_INDEX, ACTOR_SCHEMA, ACTOR_INDEX, PERMIT_SCHEMA, PERMIT_INDEXES, AUTH_SESSION_SCHEMA, AUTH_SESSION_INDEXES, API_TOKEN_SCHEMA, API_TOKEN_INDEX, BOOTSTRAP_LOCK_SCHEMA, BOOTSTRAP_LOCK_SEED, INVITE_SCHEMA, INVITE_INDEXES, APP_SETTINGS_SCHEMA, APP_SETTINGS_SEED, } from './ddl.js';
+import { AUDIT_LOG_SCHEMA, AUDIT_LOG_INDEXES } from './audit_log_schema.js';
+/** Namespace identifier for fuz_app auth migrations. */
+export const AUTH_MIGRATION_NAMESPACE = 'fuz_auth';
+/**
+ * Auth schema migrations in order.
+ *
+ * - v0: Full auth schema — account (with email_verified), actor, permit,
+ *   auth_session, api_token, audit_log (with seq), bootstrap_lock, invite,
+ *   app_settings, plus all indexes and seeds.
+ */
+export const AUTH_MIGRATIONS = [
+    // v0: full auth schema — all IF NOT EXISTS, safe for existing databases
+    {
+        name: 'full_auth_schema',
+        up: async (db) => {
+            await db.query(ACCOUNT_SCHEMA);
+            await db.query(ACCOUNT_EMAIL_INDEX);
+            await db.query(ACCOUNT_USERNAME_CI_INDEX);
+            await db.query(ACTOR_SCHEMA);
+            await db.query(ACTOR_INDEX);
+            await db.query(PERMIT_SCHEMA);
+            for (const sql of PERMIT_INDEXES) {
+                await db.query(sql); // eslint-disable-line no-await-in-loop
+            }
+            await db.query(AUTH_SESSION_SCHEMA);
+            for (const sql of AUTH_SESSION_INDEXES) {
+                await db.query(sql); // eslint-disable-line no-await-in-loop
+            }
+            await db.query(API_TOKEN_SCHEMA);
+            await db.query(API_TOKEN_INDEX);
+            await db.query(AUDIT_LOG_SCHEMA);
+            for (const sql of AUDIT_LOG_INDEXES) {
+                await db.query(sql); // eslint-disable-line no-await-in-loop
+            }
+            await db.query(BOOTSTRAP_LOCK_SCHEMA);
+            await db.query(BOOTSTRAP_LOCK_SEED);
+            await db.query(INVITE_SCHEMA);
+            for (const sql of INVITE_INDEXES) {
+                await db.query(sql); // eslint-disable-line no-await-in-loop
+            }
+            await db.query(APP_SETTINGS_SCHEMA);
+            await db.query(APP_SETTINGS_SEED);
+        },
+    },
+];
+/** Pre-composed migration namespace for auth tables. */
+export const AUTH_MIGRATION_NS = {
+    namespace: AUTH_MIGRATION_NAMESPACE,
+    migrations: AUTH_MIGRATIONS,
+};

package/dist/auth/password.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Password hashing type definitions.
+ *
+ * Defines the `PasswordHashDeps` injectable interface and `PASSWORD_LENGTH_MIN`.
+ * Concrete Argon2id implementation lives in `password_argon2.ts`.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** Minimum password length (OWASP recommendation). */
+export declare const PASSWORD_LENGTH_MIN = 12;
+/** Maximum password length. Caps hashing cost to prevent DoS via oversized passwords. */
+export declare const PASSWORD_LENGTH_MAX = 300;
+/** Password for account creation or password change — enforces current length policy. Also usable for client-side UX validation. */
+export declare const Password: z.ZodString;
+export type Password = z.infer<typeof Password>;
+/** Password submitted for login or verification — minimal validation for forward-compatibility if length requirements change. */
+export declare const PasswordProvided: z.ZodString;
+export type PasswordProvided = z.infer<typeof PasswordProvided>;
+/**
+ * Injectable password hashing dependencies.
+ *
+ * Groups all three password operations for injection in route factories
+ * and other callers. Use `Pick<PasswordHashDeps, ...>` when only a subset is needed:
+ *
+ * @example
+ * ```ts
+ * // Login handler only needs verification
+ * password: Pick<PasswordHashDeps, 'verify_password' | 'verify_dummy'>;
+ * // Bootstrap only needs hashing
+ * password: Pick<PasswordHashDeps, 'hash_password'>;
+ * ```
+ */
+export interface PasswordHashDeps {
+    hash_password: (password: string) => Promise<string>;
+    verify_password: (password: string, password_hash: string) => Promise<boolean>;
+    verify_dummy: (password: string) => Promise<boolean>;
+}
+//# sourceMappingURL=password.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"password.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/password.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,yFAAyF;AACzF,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,oIAAoI;AACpI,eAAO,MAAM,QAAQ,aAIU,CAAC;AAChC,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD,iIAAiI;AACjI,eAAO,MAAM,gBAAgB,aAIE,CAAC;AAChC,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAChC,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/E,YAAY,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACrD"}

package/dist/auth/password.js

@@ -0,0 +1,25 @@
+/**
+ * Password hashing type definitions.
+ *
+ * Defines the `PasswordHashDeps` injectable interface and `PASSWORD_LENGTH_MIN`.
+ * Concrete Argon2id implementation lives in `password_argon2.ts`.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** Minimum password length (OWASP recommendation). */
+export const PASSWORD_LENGTH_MIN = 12;
+/** Maximum password length. Caps hashing cost to prevent DoS via oversized passwords. */
+export const PASSWORD_LENGTH_MAX = 300;
+/** Password for account creation or password change — enforces current length policy. Also usable for client-side UX validation. */
+export const Password = z
+    .string()
+    .min(PASSWORD_LENGTH_MIN)
+    .max(PASSWORD_LENGTH_MAX)
+    .meta({ sensitivity: 'secret' });
+/** Password submitted for login or verification — minimal validation for forward-compatibility if length requirements change. */
+export const PasswordProvided = z
+    .string()
+    .min(1)
+    .max(PASSWORD_LENGTH_MAX)
+    .meta({ sensitivity: 'secret' });

package/dist/auth/password_argon2.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Argon2id password hashing implementation.
+ *
+ * Uses `@node-rs/argon2` for native performance with OWASP-recommended parameters.
+ * Includes timing attack resistance via `verify_dummy`.
+ *
+ * Import `argon2_password_deps` for use as `PasswordHashDeps` in `AppDeps`.
+ *
+ * @module
+ */
+import type { PasswordHashDeps } from './password.js';
+/**
+ * Hash a password using Argon2id.
+ *
+ * @param password - the plaintext password to hash
+ * @returns the Argon2id hash string
+ */
+export declare const hash_password: (password: string) => Promise<string>;
+/**
+ * Verify a password against an Argon2id hash.
+ *
+ * @param password - the plaintext password to verify
+ * @param password_hash - the Argon2id hash to verify against
+ * @returns `true` if the password matches
+ */
+export declare const verify_password: (password: string, password_hash: string) => Promise<boolean>;
+/**
+ * Verify a password against a dummy hash for timing attack resistance.
+ *
+ * Always returns `false`, but takes the same time as a real verification.
+ * Call when account lookup fails to prevent timing-based user enumeration.
+ *
+ * @param password - the plaintext password to "verify"
+ * @returns always `false`
+ */
+export declare const verify_dummy: (password: string) => Promise<boolean>;
+/**
+ * Argon2id implementation of `PasswordHashDeps`.
+ *
+ * Pass as `password` in `AppDeps` / `CreateAppBackendOptions` for production use.
+ */
+export declare const argon2_password_deps: PasswordHashDeps;
+//# sourceMappingURL=password_argon2.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"password_argon2.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/password_argon2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,eAAe,CAAC;AAiBpD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAU,UAAU,MAAM,KAAG,OAAO,CAAC,MAAM,CAEpE,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAC3B,UAAU,MAAM,EAChB,eAAe,MAAM,KACnB,OAAO,CAAC,OAAO,CAMjB,CAAC;AAKF;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GAAU,UAAU,MAAM,KAAG,OAAO,CAAC,OAAO,CAMpE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,gBAIlC,CAAC"}

package/dist/auth/password_argon2.js

@@ -0,0 +1,76 @@
+/**
+ * Argon2id password hashing implementation.
+ *
+ * Uses `@node-rs/argon2` for native performance with OWASP-recommended parameters.
+ * Includes timing attack resistance via `verify_dummy`.
+ *
+ * Import `argon2_password_deps` for use as `PasswordHashDeps` in `AppDeps`.
+ *
+ * @module
+ */
+import { hash, verify } from '@node-rs/argon2';
+/**
+ * Argon2id options following OWASP recommendations.
+ *
+ * @see https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html
+ */
+/** @node-rs/argon2 `Algorithm.Argon2id` — const enum, cannot import with isolatedModules. */
+const ARGON2ID = 2;
+const ARGON2_OPTIONS = {
+    algorithm: ARGON2ID,
+    memoryCost: 19456, // 19 MiB
+    timeCost: 2,
+    parallelism: 1,
+};
+/**
+ * Hash a password using Argon2id.
+ *
+ * @param password - the plaintext password to hash
+ * @returns the Argon2id hash string
+ */
+export const hash_password = async (password) => {
+    return hash(password, ARGON2_OPTIONS);
+};
+/**
+ * Verify a password against an Argon2id hash.
+ *
+ * @param password - the plaintext password to verify
+ * @param password_hash - the Argon2id hash to verify against
+ * @returns `true` if the password matches
+ */
+export const verify_password = async (password, password_hash) => {
+    try {
+        return await verify(password_hash, password);
+    }
+    catch {
+        return false;
+    }
+};
+/** Cached dummy hash for timing attack resistance. */
+let dummy_hash = null;
+/**
+ * Verify a password against a dummy hash for timing attack resistance.
+ *
+ * Always returns `false`, but takes the same time as a real verification.
+ * Call when account lookup fails to prevent timing-based user enumeration.
+ *
+ * @param password - the plaintext password to "verify"
+ * @returns always `false`
+ */
+export const verify_dummy = async (password) => {
+    if (!dummy_hash) {
+        dummy_hash = await hash_password('dummy_password_for_timing_resistance');
+    }
+    await verify_password(password, dummy_hash);
+    return false;
+};
+/**
+ * Argon2id implementation of `PasswordHashDeps`.
+ *
+ * Pass as `password` in `AppDeps` / `CreateAppBackendOptions` for production use.
+ */
+export const argon2_password_deps = {
+    hash_password,
+    verify_password,
+    verify_dummy,
+};

package/dist/auth/permit_queries.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Permit database queries.
+ *
+ * Permits are time-bounded, revocable grants of a role to an actor.
+ * The system is safe by default — no permit, no capability.
+ *
+ * @module
+ */
+import type { QueryDeps } from '../db/query_deps.js';
+import type { Permit, GrantPermitInput } from './account_schema.js';
+/**
+ * Grant a permit to an actor.
+ * Idempotent — if an active permit already exists for this actor and role,
+ * returns the existing permit instead of creating a duplicate.
+ *
+ * @param deps - query dependencies
+ * @param input - the permit fields
+ * @returns the created or existing active permit
+ */
+export declare const query_grant_permit: (deps: QueryDeps, input: GrantPermitInput) => Promise<Permit>;
+/**
+ * Revoke a permit by id, constrained to a specific actor.
+ *
+ * Requires `actor_id` to prevent cross-account revocation (IDOR guard).
+ * Returns `null` if the permit is not found, already revoked, or belongs
+ * to a different actor. Returns `{id, role}` on success for audit logging.
+ *
+ * @param deps - query dependencies
+ * @param permit_id - the permit to revoke
+ * @param actor_id - the actor that must own the permit
+ * @param revoked_by - the actor who revoked it (for audit trail)
+ */
+export declare const query_revoke_permit: (deps: QueryDeps, permit_id: string, actor_id: string, revoked_by: string | null) => Promise<{
+    id: string;
+    role: string;
+} | null>;
+/**
+ * Find all active (non-revoked, non-expired) permits for an actor.
+ */
+export declare const query_permit_find_active_for_actor: (deps: QueryDeps, actor_id: string) => Promise<Array<Permit>>;
+/**
+ * Check if an actor has an active permit for a given role.
+ */
+export declare const query_permit_has_role: (deps: QueryDeps, actor_id: string, role: string) => Promise<boolean>;
+/**
+ * List all permits for an actor (including revoked/expired).
+ */
+export declare const query_permit_list_for_actor: (deps: QueryDeps, actor_id: string) => Promise<Array<Permit>>;
+/**
+ * Find the account ID of an account that holds an active permit for a given role.
+ *
+ * Joins permit → actor → account. Returns the first match, or `null` if none.
+ *
+ * @param deps - query dependencies
+ * @param role - the role to search for
+ * @returns the account ID, or `null`
+ */
+export declare const query_permit_find_account_id_for_role: (deps: QueryDeps, role: string) => Promise<string | null>;
+/**
+ * Revoke the active permit for an actor with a given role.
+ *
+ * Due to the unique partial index on `(actor_id, role) WHERE revoked_at IS NULL`,
+ * at most one active permit exists per actor+role combination.
+ *
+ * @param deps - query dependencies
+ * @param actor_id - the actor whose permit to revoke
+ * @param role - the role to revoke
+ * @param revoked_by - the actor who revoked it (for audit trail)
+ * @returns `true` if a permit was revoked, `false` if none was active
+ */
+export declare const query_permit_revoke_role: (deps: QueryDeps, actor_id: string, role: string, revoked_by: string | null) => Promise<boolean>;
+//# sourceMappingURL=permit_queries.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"permit_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/permit_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAC,MAAM,EAAE,gBAAgB,EAAC,MAAM,qBAAqB,CAAC;AAGlE;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAC9B,MAAM,SAAS,EACf,OAAO,gBAAgB,KACrB,OAAO,CAAC,MAAM,CAiBhB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,WAAW,MAAM,EACjB,UAAU,MAAM,EAChB,YAAY,MAAM,GAAG,IAAI,KACvB,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAAG,IAAI,CAQ3C,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kCAAkC,GAC9C,MAAM,SAAS,EACf,UAAU,MAAM,KACd,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CASvB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,GACjC,MAAM,SAAS,EACf,UAAU,MAAM,EAChB,MAAM,MAAM,KACV,OAAO,CAAC,OAAO,CAYjB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,2BAA2B,GACvC,MAAM,SAAS,EACf,UAAU,MAAM,KACd,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAKvB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,qCAAqC,GACjD,MAAM,SAAS,EACf,MAAM,MAAM,KACV,OAAO,CAAC,MAAM,GAAG,IAAI,CAavB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,SAAS,EACf,UAAU,MAAM,EAChB,MAAM,MAAM,EACZ,YAAY,MAAM,GAAG,IAAI,KACvB,OAAO,CAAC,OAAO,CAQjB,CAAC"}

package/dist/auth/permit_queries.js

@@ -0,0 +1,116 @@
+/**
+ * Permit database queries.
+ *
+ * Permits are time-bounded, revocable grants of a role to an actor.
+ * The system is safe by default — no permit, no capability.
+ *
+ * @module
+ */
+import { assert_row } from '../db/assert_row.js';
+/**
+ * Grant a permit to an actor.
+ * Idempotent — if an active permit already exists for this actor and role,
+ * returns the existing permit instead of creating a duplicate.
+ *
+ * @param deps - query dependencies
+ * @param input - the permit fields
+ * @returns the created or existing active permit
+ */
+export const query_grant_permit = async (deps, input) => {
+    const inserted = await deps.db.query_one(`INSERT INTO permit (actor_id, role, expires_at, granted_by)
+		 VALUES ($1, $2, $3, $4)
+		 ON CONFLICT (actor_id, role) WHERE revoked_at IS NULL
+		 DO NOTHING
+		 RETURNING *`, [input.actor_id, input.role, input.expires_at?.toISOString() ?? null, input.granted_by ?? null]);
+    if (inserted)
+        return inserted;
+    // Active permit already exists — return it (idempotent grant).
+    const existing = await deps.db.query_one(`SELECT * FROM permit
+		 WHERE actor_id = $1 AND role = $2 AND revoked_at IS NULL`, [input.actor_id, input.role]);
+    return assert_row(existing, 'idempotent permit grant');
+};
+/**
+ * Revoke a permit by id, constrained to a specific actor.
+ *
+ * Requires `actor_id` to prevent cross-account revocation (IDOR guard).
+ * Returns `null` if the permit is not found, already revoked, or belongs
+ * to a different actor. Returns `{id, role}` on success for audit logging.
+ *
+ * @param deps - query dependencies
+ * @param permit_id - the permit to revoke
+ * @param actor_id - the actor that must own the permit
+ * @param revoked_by - the actor who revoked it (for audit trail)
+ */
+export const query_revoke_permit = async (deps, permit_id, actor_id, revoked_by) => {
+    const rows = await deps.db.query(`UPDATE permit SET revoked_at = NOW(), revoked_by = $3
+		 WHERE id = $1 AND actor_id = $2 AND revoked_at IS NULL
+		 RETURNING id, role`, [permit_id, actor_id, revoked_by ?? null]);
+    return rows[0] ?? null;
+};
+/**
+ * Find all active (non-revoked, non-expired) permits for an actor.
+ */
+export const query_permit_find_active_for_actor = async (deps, actor_id) => {
+    return deps.db.query(`SELECT * FROM permit
+		 WHERE actor_id = $1
+		   AND revoked_at IS NULL
+		   AND (expires_at IS NULL OR expires_at > NOW())
+		 ORDER BY created_at`, [actor_id]);
+};
+/**
+ * Check if an actor has an active permit for a given role.
+ */
+export const query_permit_has_role = async (deps, actor_id, role) => {
+    const row = await deps.db.query_one(`SELECT EXISTS(
+			SELECT 1 FROM permit
+			WHERE actor_id = $1
+			  AND role = $2
+			  AND revoked_at IS NULL
+			  AND (expires_at IS NULL OR expires_at > NOW())
+		 ) AS exists`, [actor_id, role]);
+    return row?.exists ?? false;
+};
+/**
+ * List all permits for an actor (including revoked/expired).
+ */
+export const query_permit_list_for_actor = async (deps, actor_id) => {
+    return deps.db.query(`SELECT * FROM permit WHERE actor_id = $1 ORDER BY created_at DESC`, [actor_id]);
+};
+/**
+ * Find the account ID of an account that holds an active permit for a given role.
+ *
+ * Joins permit → actor → account. Returns the first match, or `null` if none.
+ *
+ * @param deps - query dependencies
+ * @param role - the role to search for
+ * @returns the account ID, or `null`
+ */
+export const query_permit_find_account_id_for_role = async (deps, role) => {
+    const row = await deps.db.query_one(`SELECT a.id AS account_id
+		 FROM permit p
+		 JOIN actor act ON act.id = p.actor_id
+		 JOIN account a ON a.id = act.account_id
+		 WHERE p.role = $1
+		   AND p.revoked_at IS NULL
+		   AND (p.expires_at IS NULL OR p.expires_at > NOW())
+		 LIMIT 1`, [role]);
+    return row?.account_id ?? null;
+};
+/**
+ * Revoke the active permit for an actor with a given role.
+ *
+ * Due to the unique partial index on `(actor_id, role) WHERE revoked_at IS NULL`,
+ * at most one active permit exists per actor+role combination.
+ *
+ * @param deps - query dependencies
+ * @param actor_id - the actor whose permit to revoke
+ * @param role - the role to revoke
+ * @param revoked_by - the actor who revoked it (for audit trail)
+ * @returns `true` if a permit was revoked, `false` if none was active
+ */
+export const query_permit_revoke_role = async (deps, actor_id, role, revoked_by) => {
+    const rows = await deps.db.query(`UPDATE permit SET revoked_at = NOW(), revoked_by = $3
+		 WHERE actor_id = $1 AND role = $2 AND revoked_at IS NULL
+		 RETURNING id`, [actor_id, role, revoked_by ?? null]);
+    return rows.length > 0;
+};