@fuzdev/fuz_app 0.1.0

package/dist/auth/account_schema.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Auth entity types and client-safe schemas.
+ *
+ * Defines the runtime types for the fuz identity system:
+ * `Account`, `Actor`, `Permit`, `AuthSession`, and `ApiToken`.
+ *
+ * DDL lives in `ddl.ts`; role system in `role_schema.ts`.
+ * See docs/identity.md for design rationale.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** Minimum username length (must have start + middle + end characters). */
+export declare const USERNAME_LENGTH_MIN = 3;
+/** Maximum username length (matches GitHub's limit). */
+export declare const USERNAME_LENGTH_MAX = 39;
+/** Maximum length for username input on login/lookup — more permissive than `USERNAME_LENGTH_MAX` for forward-compatibility if the creation limit is raised. */
+export declare const USERNAME_PROVIDED_LENGTH_MAX = 255;
+/** Username for account creation — starts with letter, alphanumeric/dash/underscore middle, ends with alphanumeric. No @ or . allowed. */
+export declare const Username: z.ZodString;
+export type Username = z.infer<typeof Username>;
+/** Username submitted for login or lookup — minimal validation for forward-compatibility if format rules change. */
+export declare const UsernameProvided: z.ZodString;
+export type UsernameProvided = z.infer<typeof UsernameProvided>;
+/** Email validation. */
+export declare const Email: z.ZodEmail;
+export type Email = z.infer<typeof Email>;
+/** Account — authentication identity. You log in as an account. */
+export interface Account {
+    id: string;
+    username: Username;
+    email: Email | null;
+    email_verified: boolean;
+    password_hash: string;
+    created_at: string;
+    created_by: string | null;
+    updated_at: string;
+    updated_by: string | null;
+}
+/** Account without sensitive fields, scoped to the authenticated user's own session. */
+export interface SessionAccount {
+    id: string;
+    username: Username;
+    email: Email | null;
+    email_verified: boolean;
+    created_at: string;
+}
+/** Actor — the entity that acts. Owns cells, holds permits, appears in audit trails. */
+export interface Actor {
+    id: string;
+    account_id: string;
+    name: string;
+    created_at: string;
+    updated_at: string | null;
+    updated_by: string | null;
+}
+/** Permit — time-bounded, revocable grant of a role to an actor. */
+export interface Permit {
+    id: string;
+    actor_id: string;
+    role: string;
+    created_at: string;
+    expires_at: string | null;
+    revoked_at: string | null;
+    revoked_by: string | null;
+    granted_by: string | null;
+}
+export declare const is_permit_active: (p: Permit, now?: Date) => boolean;
+/** Server-side auth session, keyed by blake3 hash of session token. */
+export interface AuthSession {
+    id: string;
+    account_id: string;
+    created_at: string;
+    expires_at: string;
+    last_seen_at: string;
+}
+/** API token for CLI/programmatic access. */
+export interface ApiToken {
+    id: string;
+    account_id: string;
+    name: string;
+    token_hash: string;
+    expires_at: string | null;
+    last_used_at: string | null;
+    last_used_ip: string | null;
+    created_at: string;
+}
+/** Zod schema for `SessionAccount` — account without sensitive fields. */
+export declare const SessionAccountJson: z.ZodObject<{
+    id: z.ZodString;
+    username: z.ZodString;
+    email: z.ZodNullable<z.ZodEmail>;
+    email_verified: z.ZodBoolean;
+    created_at: z.ZodString;
+}, z.core.$strict>;
+export type SessionAccountJson = z.infer<typeof SessionAccountJson>;
+/** Zod schema for `AuthSession` — id is the blake3 hash, safe for client. */
+export declare const AuthSessionJson: z.ZodObject<{
+    id: z.ZodString;
+    account_id: z.ZodString;
+    created_at: z.ZodString;
+    expires_at: z.ZodString;
+    last_seen_at: z.ZodString;
+}, z.core.$strict>;
+export type AuthSessionJson = z.infer<typeof AuthSessionJson>;
+/** Zod schema for client-safe API token listing (excludes `token_hash`). */
+export declare const ClientApiTokenJson: z.ZodObject<{
+    id: z.ZodString;
+    account_id: z.ZodString;
+    name: z.ZodString;
+    expires_at: z.ZodNullable<z.ZodString>;
+    last_used_at: z.ZodNullable<z.ZodString>;
+    last_used_ip: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodString;
+}, z.core.$strict>;
+export type ClientApiTokenJson = z.infer<typeof ClientApiTokenJson>;
+/** Zod schema for the permit summary returned in admin account listings. */
+export declare const PermitSummaryJson: z.ZodObject<{
+    id: z.ZodString;
+    role: z.ZodString;
+    created_at: z.ZodString;
+    expires_at: z.ZodNullable<z.ZodString>;
+    granted_by: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type PermitSummaryJson = z.infer<typeof PermitSummaryJson>;
+/** Zod schema for the actor summary returned in admin account listings. */
+export declare const ActorSummaryJson: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strict>;
+export type ActorSummaryJson = z.infer<typeof ActorSummaryJson>;
+/** Zod schema for admin-facing account data — extends `SessionAccountJson` with audit fields. */
+export declare const AdminAccountJson: z.ZodObject<{
+    id: z.ZodString;
+    username: z.ZodString;
+    email: z.ZodNullable<z.ZodEmail>;
+    email_verified: z.ZodBoolean;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+    updated_by: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type AdminAccountJson = z.infer<typeof AdminAccountJson>;
+/** Zod schema for an admin account listing entry (account + actor + permits). */
+export declare const AdminAccountEntryJson: z.ZodObject<{
+    account: z.ZodObject<{
+        id: z.ZodString;
+        username: z.ZodString;
+        email: z.ZodNullable<z.ZodEmail>;
+        email_verified: z.ZodBoolean;
+        created_at: z.ZodString;
+        updated_at: z.ZodString;
+        updated_by: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    actor: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>>;
+    permits: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodString;
+        created_at: z.ZodString;
+        expires_at: z.ZodNullable<z.ZodString>;
+        granted_by: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AdminAccountEntryJson = z.infer<typeof AdminAccountEntryJson>;
+export interface CreateAccountInput {
+    username: Username;
+    password_hash: string;
+    email?: Email | null;
+}
+export interface GrantPermitInput {
+    actor_id: string;
+    role: string;
+    expires_at?: Date | null;
+    granted_by: string | null;
+}
+/**
+ * Convert an `Account` to a `SessionAccount` by stripping sensitive fields.
+ *
+ * @param account - the full account record
+ * @returns the client-safe account
+ */
+export declare const to_session_account: (account: Account) => SessionAccount;
+/**
+ * Convert an `Account` to an `AdminAccountJson` for admin listings.
+ *
+ * @param account - the full account record
+ * @returns the admin-safe account with audit fields
+ */
+export declare const to_admin_account: (account: Account) => AdminAccountJson;
+//# sourceMappingURL=account_schema.d.ts.map

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

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

package/dist/auth/account_schema.js

@@ -0,0 +1,105 @@
+/**
+ * Auth entity types and client-safe schemas.
+ *
+ * Defines the runtime types for the fuz identity system:
+ * `Account`, `Actor`, `Permit`, `AuthSession`, and `ApiToken`.
+ *
+ * DDL lives in `ddl.ts`; role system in `role_schema.ts`.
+ * See docs/identity.md for design rationale.
+ *
+ * @module
+ */
+import { z } from 'zod';
+// TODO consider `.brand()` on Username and Email for compile-time safety
+/** Minimum username length (must have start + middle + end characters). */
+export const USERNAME_LENGTH_MIN = 3;
+/** Maximum username length (matches GitHub's limit). */
+export const USERNAME_LENGTH_MAX = 39;
+/** Maximum length for username input on login/lookup — more permissive than `USERNAME_LENGTH_MAX` for forward-compatibility if the creation limit is raised. */
+export const USERNAME_PROVIDED_LENGTH_MAX = 255;
+/** Username for account creation — starts with letter, alphanumeric/dash/underscore middle, ends with alphanumeric. No @ or . allowed. */
+export const Username = z
+    .string()
+    .min(USERNAME_LENGTH_MIN)
+    .max(USERNAME_LENGTH_MAX)
+    .regex(/^[a-zA-Z][0-9a-zA-Z_-]*[0-9a-zA-Z]$/);
+/** Username submitted for login or lookup — minimal validation for forward-compatibility if format rules change. */
+export const UsernameProvided = z.string().min(1).max(USERNAME_PROVIDED_LENGTH_MAX);
+/** Email validation. */
+export const Email = z.email();
+export const is_permit_active = (p, now = new Date()) => !p.revoked_at && (!p.expires_at || new Date(p.expires_at) > now);
+// Client-safe Zod schemas — for route output validation and ActionSpec outputs.
+/** Zod schema for `SessionAccount` — account without sensitive fields. */
+export const SessionAccountJson = z.strictObject({
+    id: z.string(),
+    username: Username,
+    email: Email.nullable(),
+    email_verified: z.boolean(),
+    created_at: z.string(),
+});
+/** Zod schema for `AuthSession` — id is the blake3 hash, safe for client. */
+export const AuthSessionJson = z.strictObject({
+    id: z.string(),
+    account_id: z.string(),
+    created_at: z.string(),
+    expires_at: z.string(),
+    last_seen_at: z.string(),
+});
+/** Zod schema for client-safe API token listing (excludes `token_hash`). */
+export const ClientApiTokenJson = z.strictObject({
+    id: z.string(),
+    account_id: z.string(),
+    name: z.string(),
+    expires_at: z.string().nullable(),
+    last_used_at: z.string().nullable(),
+    last_used_ip: z.string().nullable(),
+    created_at: z.string(),
+});
+/** Zod schema for the permit summary returned in admin account listings. */
+export const PermitSummaryJson = z.strictObject({
+    id: z.string(),
+    role: z.string(),
+    created_at: z.string(),
+    expires_at: z.string().nullable(),
+    granted_by: z.string().nullable(),
+});
+/** Zod schema for the actor summary returned in admin account listings. */
+export const ActorSummaryJson = z.strictObject({
+    id: z.string(),
+    name: z.string(),
+});
+/** Zod schema for admin-facing account data — extends `SessionAccountJson` with audit fields. */
+export const AdminAccountJson = SessionAccountJson.extend({
+    updated_at: z.string(),
+    updated_by: z.string().nullable(),
+});
+/** Zod schema for an admin account listing entry (account + actor + permits). */
+export const AdminAccountEntryJson = z.strictObject({
+    account: AdminAccountJson,
+    actor: ActorSummaryJson.nullable(),
+    permits: z.array(PermitSummaryJson),
+});
+/**
+ * Convert an `Account` to a `SessionAccount` by stripping sensitive fields.
+ *
+ * @param account - the full account record
+ * @returns the client-safe account
+ */
+export const to_session_account = (account) => ({
+    id: account.id,
+    username: account.username,
+    email: account.email,
+    email_verified: account.email_verified,
+    created_at: account.created_at,
+});
+/**
+ * Convert an `Account` to an `AdminAccountJson` for admin listings.
+ *
+ * @param account - the full account record
+ * @returns the admin-safe account with audit fields
+ */
+export const to_admin_account = (account) => ({
+    ...to_session_account(account),
+    updated_at: account.updated_at,
+    updated_by: account.updated_by,
+});

package/dist/auth/admin_routes.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Generic admin route specs — account listing, permit management, session and token revocation.
+ *
+ * All routes require the `admin` role.
+ *
+ * @module
+ */
+import { type RoleSchemaResult } from './role_schema.js';
+import { type RouteSpec } from '../http/route_spec.js';
+import type { RouteFactoryDeps } from './deps.js';
+/** Options for admin route specs. */
+export interface AdminRouteOptions {
+    /**
+     * Role schema result from `create_role_schema()`. Defaults to builtin roles only.
+     * Pass the full result to enable extended app-defined roles in the admin UI.
+     * Both `Role` and `role_options` come from the same call — passing them together
+     * via this field ensures they stay in sync.
+     */
+    roles?: RoleSchemaResult;
+}
+/**
+ * Create admin route specs for account listing and permit management.
+ *
+ * @param deps - stateless capabilities (log)
+ * @param options - optional options with role schema for validation
+ * @returns route specs for admin account management
+ */
+export declare const create_admin_account_route_specs: (deps: Pick<RouteFactoryDeps, "log" | "on_audit_event">, options?: AdminRouteOptions) => Array<RouteSpec>;
+//# sourceMappingURL=admin_routes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"admin_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/admin_routes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAA8C,KAAK,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAGpG,OAAO,EAAoC,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAUxF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAShD,qCAAqC;AACrC,MAAM,WAAW,iBAAiB;IACjC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,gBAAgB,CAAC,EACtD,UAAU,iBAAiB,KACzB,KAAK,CAAC,SAAS,CAoMjB,CAAC"}

package/dist/auth/admin_routes.js

@@ -0,0 +1,193 @@
+/**
+ * Generic admin route specs — account listing, permit management, session and token revocation.
+ *
+ * All routes require the `admin` role.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { BUILTIN_ROLE_OPTIONS, BuiltinRole, RoleName } from './role_schema.js';
+import { AdminAccountEntryJson } from './account_schema.js';
+import { require_request_context } from './request_context.js';
+import { get_route_input, get_route_params } from '../http/route_spec.js';
+import { query_account_by_id, query_actor_by_account, query_admin_account_list, } from './account_queries.js';
+import { query_grant_permit, query_revoke_permit } from './permit_queries.js';
+import { query_session_revoke_all_for_account } from './session_queries.js';
+import { query_revoke_all_api_tokens_for_account } from './api_token_queries.js';
+import { audit_log_fire_and_forget } from './audit_log_queries.js';
+import { ERROR_ACCOUNT_NOT_FOUND, ERROR_ROLE_NOT_WEB_GRANTABLE, ERROR_PERMIT_NOT_FOUND, ERROR_INSUFFICIENT_PERMISSIONS, } from '../http/error_schemas.js';
+import { get_client_ip } from '../http/proxy.js';
+/**
+ * Create admin route specs for account listing and permit management.
+ *
+ * @param deps - stateless capabilities (log)
+ * @param options - optional options with role schema for validation
+ * @returns route specs for admin account management
+ */
+export const create_admin_account_route_specs = (deps, options) => {
+    const role = 'admin';
+    const { on_audit_event } = deps;
+    const role_schema = options?.roles?.Role ?? BuiltinRole;
+    const role_options = options?.roles?.role_options ?? BUILTIN_ROLE_OPTIONS;
+    const grantable_roles = [];
+    for (const [name, rc] of role_options) {
+        if (rc.web_grantable)
+            grantable_roles.push(name);
+    }
+    return [
+        {
+            method: 'GET',
+            path: '/accounts',
+            auth: { type: 'role', role },
+            description: 'List all accounts with their permits',
+            input: z.null(),
+            output: z.strictObject({
+                accounts: z.array(AdminAccountEntryJson),
+                grantable_roles: z.array(RoleName),
+            }),
+            handler: async (c, route) => {
+                const accounts = await query_admin_account_list(route);
+                return c.json({ accounts, grantable_roles });
+            },
+        },
+        {
+            method: 'POST',
+            path: '/accounts/:account_id/permits/grant',
+            auth: { type: 'role', role },
+            description: 'Grant a role permit to an account',
+            params: z.strictObject({ account_id: z.uuid() }),
+            input: z.strictObject({ role: role_schema }),
+            output: z.strictObject({
+                ok: z.literal(true),
+                permit: z.strictObject({ id: z.string(), role: z.string() }),
+            }),
+            errors: {
+                403: z.looseObject({
+                    error: z.enum([ERROR_INSUFFICIENT_PERMISSIONS, ERROR_ROLE_NOT_WEB_GRANTABLE]),
+                }),
+                404: z.looseObject({ error: z.literal(ERROR_ACCOUNT_NOT_FOUND) }),
+            },
+            handler: async (c, route) => {
+                const { account_id } = get_route_params(c);
+                const { role: role_name } = get_route_input(c);
+                // Enforce web_grantable — direct API calls must respect the same
+                // restrictions as the UI. Keeper role can only be granted via daemon token.
+                const rc = role_options.get(role_name);
+                if (!rc?.web_grantable) {
+                    return c.json({ error: ERROR_ROLE_NOT_WEB_GRANTABLE }, 403);
+                }
+                const actor = await query_actor_by_account(route, account_id);
+                if (!actor) {
+                    return c.json({ error: ERROR_ACCOUNT_NOT_FOUND }, 404);
+                }
+                const ctx = require_request_context(c);
+                const permit = await query_grant_permit(route, {
+                    actor_id: actor.id,
+                    role: role_name,
+                    granted_by: ctx.actor.id,
+                });
+                void audit_log_fire_and_forget(route, {
+                    event_type: 'permit_grant',
+                    actor_id: ctx.actor.id,
+                    account_id: ctx.account.id,
+                    target_account_id: account_id,
+                    ip: get_client_ip(c),
+                    metadata: { role: role_name, permit_id: permit.id },
+                }, deps.log, on_audit_event);
+                return c.json({ ok: true, permit: { id: permit.id, role: permit.role } });
+            },
+        },
+        {
+            method: 'POST',
+            path: '/accounts/:account_id/sessions/revoke-all',
+            auth: { type: 'role', role },
+            description: 'Revoke all sessions for an account',
+            params: z.strictObject({ account_id: z.uuid() }),
+            input: z.null(),
+            output: z.strictObject({ ok: z.literal(true), count: z.number() }),
+            errors: { 404: z.looseObject({ error: z.literal(ERROR_ACCOUNT_NOT_FOUND) }) },
+            handler: async (c, route) => {
+                const { account_id } = get_route_params(c);
+                const account = await query_account_by_id(route, account_id);
+                if (!account) {
+                    return c.json({ error: ERROR_ACCOUNT_NOT_FOUND }, 404);
+                }
+                const ctx = require_request_context(c);
+                const count = await query_session_revoke_all_for_account(route, account_id);
+                void audit_log_fire_and_forget(route, {
+                    event_type: 'session_revoke_all',
+                    actor_id: ctx.actor.id,
+                    account_id: ctx.account.id,
+                    target_account_id: account_id,
+                    ip: get_client_ip(c),
+                    metadata: { count },
+                }, deps.log, on_audit_event);
+                return c.json({ ok: true, count });
+            },
+        },
+        {
+            method: 'POST',
+            path: '/accounts/:account_id/tokens/revoke-all',
+            auth: { type: 'role', role },
+            description: 'Revoke all API tokens for an account',
+            params: z.strictObject({ account_id: z.uuid() }),
+            input: z.null(),
+            output: z.strictObject({ ok: z.literal(true), count: z.number() }),
+            errors: { 404: z.looseObject({ error: z.literal(ERROR_ACCOUNT_NOT_FOUND) }) },
+            handler: async (c, route) => {
+                const { account_id } = get_route_params(c);
+                const account = await query_account_by_id(route, account_id);
+                if (!account) {
+                    return c.json({ error: ERROR_ACCOUNT_NOT_FOUND }, 404);
+                }
+                const ctx = require_request_context(c);
+                const count = await query_revoke_all_api_tokens_for_account(route, account_id);
+                void audit_log_fire_and_forget(route, {
+                    event_type: 'token_revoke_all',
+                    actor_id: ctx.actor.id,
+                    account_id: ctx.account.id,
+                    target_account_id: account_id,
+                    ip: get_client_ip(c),
+                    metadata: { count },
+                }, deps.log, on_audit_event);
+                return c.json({ ok: true, count });
+            },
+        },
+        {
+            method: 'POST',
+            path: '/accounts/:account_id/permits/:permit_id/revoke',
+            auth: { type: 'role', role },
+            description: 'Revoke a permit',
+            params: z.strictObject({ account_id: z.uuid(), permit_id: z.uuid() }),
+            input: z.null(),
+            output: z.strictObject({ ok: z.literal(true), revoked: z.literal(true) }),
+            errors: {
+                404: z.looseObject({
+                    error: z.enum([ERROR_ACCOUNT_NOT_FOUND, ERROR_PERMIT_NOT_FOUND]),
+                }),
+            },
+            handler: async (c, route) => {
+                const { account_id, permit_id } = get_route_params(c);
+                const ctx = require_request_context(c);
+                // resolve the target actor from the URL account_id to prevent IDOR
+                const target_actor = await query_actor_by_account(route, account_id);
+                if (!target_actor) {
+                    return c.json({ error: ERROR_ACCOUNT_NOT_FOUND }, 404);
+                }
+                const result = await query_revoke_permit(route, permit_id, target_actor.id, ctx.actor.id);
+                if (!result) {
+                    return c.json({ error: ERROR_PERMIT_NOT_FOUND }, 404);
+                }
+                void audit_log_fire_and_forget(route, {
+                    event_type: 'permit_revoke',
+                    actor_id: ctx.actor.id,
+                    account_id: ctx.account.id,
+                    target_account_id: account_id,
+                    ip: get_client_ip(c),
+                    metadata: { role: result.role, permit_id },
+                }, deps.log, on_audit_event);
+                return c.json({ ok: true, revoked: true });
+            },
+        },
+    ];
+};

package/dist/auth/api_token.d.ts

@@ -0,0 +1,33 @@
+/**
+ * API token generation and hashing utilities.
+ *
+ * Tokens use the format `secret_fuz_token_<base64url>` and are stored
+ * as blake3 hashes. These are pure cryptographic operations with no
+ * framework dependency — the bearer auth middleware that validates
+ * tokens lives in `bearer_auth.ts`.
+ *
+ * @module
+ */
+/** Prefix for all fuz API tokens (enables secret scanning). */
+export declare const API_TOKEN_PREFIX = "secret_fuz_token_";
+/**
+ * Hash an API token for storage using blake3.
+ *
+ * @param token - the raw API token
+ * @returns hex-encoded blake3 hash
+ */
+export declare const hash_api_token: (token: string) => string;
+/**
+ * Generate a new API token with its hash and public id.
+ *
+ * The raw token is returned exactly once — callers must present it
+ * to the user immediately.
+ *
+ * @returns the raw token, a public id, and the blake3 hash for storage
+ */
+export declare const generate_api_token: () => {
+    token: string;
+    id: string;
+    token_hash: string;
+};
+//# sourceMappingURL=api_token.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"api_token.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/api_token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,MAA4B,CAAC;AAE5E;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,QAAO;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAMnF,CAAC"}

package/dist/auth/api_token.js

@@ -0,0 +1,36 @@
+/**
+ * API token generation and hashing utilities.
+ *
+ * Tokens use the format `secret_fuz_token_<base64url>` and are stored
+ * as blake3 hashes. These are pure cryptographic operations with no
+ * framework dependency — the bearer auth middleware that validates
+ * tokens lives in `bearer_auth.ts`.
+ *
+ * @module
+ */
+import { hash_blake3 } from '@fuzdev/fuz_util/hash_blake3.js';
+import { generate_random_base64url } from '../crypto.js';
+/** Prefix for all fuz API tokens (enables secret scanning). */
+export const API_TOKEN_PREFIX = 'secret_fuz_token_';
+/**
+ * Hash an API token for storage using blake3.
+ *
+ * @param token - the raw API token
+ * @returns hex-encoded blake3 hash
+ */
+export const hash_api_token = (token) => hash_blake3(token);
+/**
+ * Generate a new API token with its hash and public id.
+ *
+ * The raw token is returned exactly once — callers must present it
+ * to the user immediately.
+ *
+ * @returns the raw token, a public id, and the blake3 hash for storage
+ */
+export const generate_api_token = () => {
+    const raw = generate_random_base64url();
+    const token = `${API_TOKEN_PREFIX}${raw}`;
+    const token_hash = hash_api_token(token);
+    const id = `tok_${raw.slice(0, 12)}`;
+    return { token, id, token_hash };
+};