@fuzdev/fuz_app 0.1.0

package/dist/http/error_schemas.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Standard error response schemas and error code constants for fuz_app routes.
+ *
+ * Defines `ERROR_*` constants (single source of truth for machine-parseable
+ * error codes), Zod schemas for error response shapes, a type for error schema
+ * maps, and `derive_error_schemas` to auto-populate middleware-produced errors
+ * from a route's auth requirement and input schema.
+ *
+ * Used in `RouteSpec.errors` and `MiddlewareSpec.errors` for surface
+ * introspection and DEV-mode validation.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import type { RouteAuth } from './route_spec.js';
+/** Request body failed Zod validation. */
+export declare const ERROR_INVALID_REQUEST_BODY: "invalid_request_body";
+/** Request body is not valid JSON or not an object. */
+export declare const ERROR_INVALID_JSON_BODY: "invalid_json_body";
+/** URL path params failed Zod validation. */
+export declare const ERROR_INVALID_ROUTE_PARAMS: "invalid_route_params";
+/** URL query params failed Zod validation. */
+export declare const ERROR_INVALID_QUERY_PARAMS: "invalid_query_params";
+/** No valid session or bearer token. */
+export declare const ERROR_AUTHENTICATION_REQUIRED: "authentication_required";
+/** Authenticated but missing required role. */
+export declare const ERROR_INSUFFICIENT_PERMISSIONS: "insufficient_permissions";
+/** Rate limiter rejected the request. */
+export declare const ERROR_RATE_LIMIT_EXCEEDED: "rate_limit_exceeded";
+/** Username or password is wrong (intentionally vague for enumeration prevention). */
+export declare const ERROR_INVALID_CREDENTIALS: "invalid_credentials";
+/** Request body exceeds the maximum allowed size. */
+export declare const ERROR_PAYLOAD_TOO_LARGE: "payload_too_large";
+/** Request origin not in allowlist. */
+export declare const ERROR_FORBIDDEN_ORIGIN: "forbidden_origin";
+/** Request referer not in allowlist. */
+export declare const ERROR_FORBIDDEN_REFERER: "forbidden_referer";
+/** Bearer token sent with Origin/Referer header (browser context). */
+export declare const ERROR_BEARER_REJECTED_BROWSER: "bearer_token_rejected_in_browser_context";
+/** Bearer token failed validation (missing, malformed, or revoked). */
+export declare const ERROR_INVALID_TOKEN: "invalid_token";
+/** Token references a deleted account. */
+export declare const ERROR_ACCOUNT_NOT_FOUND: "account_not_found";
+/** Keeper routes require daemon_token credential type. */
+export declare const ERROR_KEEPER_REQUIRES_DAEMON_TOKEN: "keeper_requires_daemon_token";
+/** Daemon token header present but malformed or not matching current/previous token. */
+export declare const ERROR_INVALID_DAEMON_TOKEN: "invalid_daemon_token";
+/** Daemon token valid but keeper account not yet resolved (pre-bootstrap). */
+export declare const ERROR_KEEPER_ACCOUNT_NOT_CONFIGURED: "keeper_account_not_configured";
+/** Keeper account ID set but account row not found. */
+export declare const ERROR_KEEPER_ACCOUNT_NOT_FOUND: "keeper_account_not_found";
+/** Bootstrap lock already acquired — system already bootstrapped. */
+export declare const ERROR_ALREADY_BOOTSTRAPPED: "already_bootstrapped";
+/** Bootstrap token file not found on disk. */
+export declare const ERROR_TOKEN_FILE_MISSING: "token_file_missing";
+/** Bootstrap endpoint called but no token path configured. */
+export declare const ERROR_BOOTSTRAP_NOT_CONFIGURED: "bootstrap_not_configured";
+/** No unclaimed invite matches the signup credentials. */
+export declare const ERROR_NO_MATCHING_INVITE: "no_matching_invite";
+/** Signup conflict — username or email already taken (intentionally vague for enumeration prevention). */
+export declare const ERROR_SIGNUP_CONFLICT: "signup_conflict";
+/** Invite not found (for delete operations). */
+export declare const ERROR_INVITE_NOT_FOUND: "invite_not_found";
+/** Invite must have at least an email or username. */
+export declare const ERROR_INVITE_MISSING_IDENTIFIER: "invite_missing_identifier";
+/** An unclaimed invite already exists for this email or username. */
+export declare const ERROR_INVITE_DUPLICATE: "invite_duplicate";
+/** An account already exists with this invite's username. */
+export declare const ERROR_INVITE_ACCOUNT_EXISTS_USERNAME: "invite_account_exists_username";
+/** An account already exists with this invite's email. */
+export declare const ERROR_INVITE_ACCOUNT_EXISTS_EMAIL: "invite_account_exists_email";
+/** Admin tried to grant a role that is not web-grantable. */
+export declare const ERROR_ROLE_NOT_WEB_GRANTABLE: "role_not_web_grantable";
+/** Permit ID not found or not owned by the target actor. */
+export declare const ERROR_PERMIT_NOT_FOUND: "permit_not_found";
+/** Query parameter `event_type` is not a valid audit event type. */
+export declare const ERROR_INVALID_EVENT_TYPE: "invalid_event_type";
+/** DELETE blocked by a foreign key constraint. */
+export declare const ERROR_FOREIGN_KEY_VIOLATION: "foreign_key_violation";
+/** Table name not found in `information_schema`. */
+export declare const ERROR_TABLE_NOT_FOUND: "table_not_found";
+/** Table has no primary key constraint (cannot delete by PK). */
+export declare const ERROR_TABLE_NO_PRIMARY_KEY: "table_no_primary_key";
+/** Row with the given PK value not found. */
+export declare const ERROR_ROW_NOT_FOUND: "row_not_found";
+/** Base API error — all JSON error responses have at least `{error: string}`. */
+export declare const ApiError: z.ZodObject<{
+    error: z.ZodString;
+}, z.core.$loose>;
+export type ApiError = z.infer<typeof ApiError>;
+/**
+ * Input validation error — returned when the request body fails Zod parsing.
+ *
+ * `issues` contains the Zod validation issues for diagnostic display.
+ */
+export declare const ValidationError: z.ZodObject<{
+    error: z.ZodString;
+    issues: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type ValidationError = z.infer<typeof ValidationError>;
+/** Permission error — returned by `require_role()` when the required role is missing. */
+export declare const PermissionError: z.ZodObject<{
+    error: z.ZodLiteral<"insufficient_permissions">;
+    required_role: z.ZodString;
+}, z.core.$loose>;
+export type PermissionError = z.infer<typeof PermissionError>;
+/** Keeper credential error — returned by `require_keeper` when credential type is wrong. */
+export declare const KeeperError: z.ZodObject<{
+    error: z.ZodLiteral<"keeper_requires_daemon_token">;
+    credential_type: z.ZodString;
+}, z.core.$loose>;
+export type KeeperError = z.infer<typeof KeeperError>;
+/** Rate limit error — returned when a rate limiter rejects the request. */
+export declare const RateLimitError: z.ZodObject<{
+    error: z.ZodLiteral<"rate_limit_exceeded">;
+    retry_after: z.ZodNumber;
+}, z.core.$loose>;
+export type RateLimitError = z.infer<typeof RateLimitError>;
+/** Payload too large error — returned when the request body exceeds the size limit. */
+export declare const PayloadTooLargeError: z.ZodObject<{
+    error: z.ZodLiteral<"payload_too_large">;
+}, z.core.$loose>;
+export type PayloadTooLargeError = z.infer<typeof PayloadTooLargeError>;
+/** Foreign key violation error — returned when a delete is blocked by references. */
+export declare const ForeignKeyError: z.ZodObject<{
+    error: z.ZodLiteral<"foreign_key_violation">;
+}, z.core.$loose>;
+export type ForeignKeyError = z.infer<typeof ForeignKeyError>;
+/**
+ * Error schema map — maps HTTP status codes to Zod schemas.
+ *
+ * Used on `RouteSpec.errors` and internally by `derive_error_schemas`.
+ */
+export type RouteErrorSchemas = Partial<Record<number, z.ZodType>>;
+/**
+ * Rate limit key type — declares what a route's rate limiter is keyed on.
+ *
+ * - `'ip'` — per-IP rate limiting (bootstrap, password change, bearer auth)
+ * - `'account'` — per-account rate limiting (keyed on submitted identifier)
+ * - `'both'` — both per-IP and per-account (login)
+ */
+export type RateLimitKey = 'ip' | 'account' | 'both';
+/**
+ * Derive error schemas from a route's auth requirement, input schema, and rate limit config.
+ *
+ * Returns the error schemas that middleware will auto-produce for this route.
+ * Route handlers can declare additional error schemas via `RouteSpec.errors`;
+ * explicit entries override auto-derived ones for the same status code.
+ *
+ * Derivation rules:
+ * - **Has input schema** (non-null) or **has params schema** or **has query schema**: 400 (validation error with issues)
+ * - **auth: authenticated**: 401
+ * - **auth: role**: 401 + 403 (with `required_role`)
+ * - **auth: keeper**: 401 + 403 (keeper-specific)
+ * - **rate_limit**: 429 (rate limit exceeded with `retry_after`)
+ *
+ * @param auth - the route's auth requirement
+ * @param has_input - whether the route has a non-null input schema
+ * @param has_params - whether the route has a params schema
+ * @param has_query - whether the route has a query schema
+ * @param rate_limit - the rate limit key type, if any
+ * @returns error schemas keyed by HTTP status code
+ */
+export declare const derive_error_schemas: (auth: RouteAuth, has_input: boolean, has_params?: boolean, has_query?: boolean, rate_limit?: RateLimitKey) => RouteErrorSchemas;
+//# sourceMappingURL=error_schemas.d.ts.map

package/dist/http/error_schemas.d.ts.map

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

package/dist/http/error_schemas.js

@@ -0,0 +1,178 @@
+/**
+ * Standard error response schemas and error code constants for fuz_app routes.
+ *
+ * Defines `ERROR_*` constants (single source of truth for machine-parseable
+ * error codes), Zod schemas for error response shapes, a type for error schema
+ * maps, and `derive_error_schemas` to auto-populate middleware-produced errors
+ * from a route's auth requirement and input schema.
+ *
+ * Used in `RouteSpec.errors` and `MiddlewareSpec.errors` for surface
+ * introspection and DEV-mode validation.
+ *
+ * @module
+ */
+import { z } from 'zod';
+// --- Core: Validation (auto-derived by route spec middleware) ---
+/** Request body failed Zod validation. */
+export const ERROR_INVALID_REQUEST_BODY = 'invalid_request_body';
+/** Request body is not valid JSON or not an object. */
+export const ERROR_INVALID_JSON_BODY = 'invalid_json_body';
+/** URL path params failed Zod validation. */
+export const ERROR_INVALID_ROUTE_PARAMS = 'invalid_route_params';
+/** URL query params failed Zod validation. */
+export const ERROR_INVALID_QUERY_PARAMS = 'invalid_query_params';
+// --- Core: Authentication & authorization (auto-derived by auth middleware) ---
+/** No valid session or bearer token. */
+export const ERROR_AUTHENTICATION_REQUIRED = 'authentication_required';
+/** Authenticated but missing required role. */
+export const ERROR_INSUFFICIENT_PERMISSIONS = 'insufficient_permissions';
+/** Rate limiter rejected the request. */
+export const ERROR_RATE_LIMIT_EXCEEDED = 'rate_limit_exceeded';
+/** Username or password is wrong (intentionally vague for enumeration prevention). */
+export const ERROR_INVALID_CREDENTIALS = 'invalid_credentials';
+/** Request body exceeds the maximum allowed size. */
+export const ERROR_PAYLOAD_TOO_LARGE = 'payload_too_large';
+// --- Origin & bearer token verification ---
+/** Request origin not in allowlist. */
+export const ERROR_FORBIDDEN_ORIGIN = 'forbidden_origin';
+/** Request referer not in allowlist. */
+export const ERROR_FORBIDDEN_REFERER = 'forbidden_referer';
+/** Bearer token sent with Origin/Referer header (browser context). */
+export const ERROR_BEARER_REJECTED_BROWSER = 'bearer_token_rejected_in_browser_context';
+/** Bearer token failed validation (missing, malformed, or revoked). */
+export const ERROR_INVALID_TOKEN = 'invalid_token';
+/** Token references a deleted account. */
+export const ERROR_ACCOUNT_NOT_FOUND = 'account_not_found';
+// --- Keeper / daemon token ---
+/** Keeper routes require daemon_token credential type. */
+export const ERROR_KEEPER_REQUIRES_DAEMON_TOKEN = 'keeper_requires_daemon_token';
+/** Daemon token header present but malformed or not matching current/previous token. */
+export const ERROR_INVALID_DAEMON_TOKEN = 'invalid_daemon_token';
+/** Daemon token valid but keeper account not yet resolved (pre-bootstrap). */
+export const ERROR_KEEPER_ACCOUNT_NOT_CONFIGURED = 'keeper_account_not_configured';
+/** Keeper account ID set but account row not found. */
+export const ERROR_KEEPER_ACCOUNT_NOT_FOUND = 'keeper_account_not_found';
+// --- Bootstrap ---
+/** Bootstrap lock already acquired — system already bootstrapped. */
+export const ERROR_ALREADY_BOOTSTRAPPED = 'already_bootstrapped';
+/** Bootstrap token file not found on disk. */
+export const ERROR_TOKEN_FILE_MISSING = 'token_file_missing';
+/** Bootstrap endpoint called but no token path configured. */
+export const ERROR_BOOTSTRAP_NOT_CONFIGURED = 'bootstrap_not_configured';
+// --- Signup / Invites ---
+/** No unclaimed invite matches the signup credentials. */
+export const ERROR_NO_MATCHING_INVITE = 'no_matching_invite';
+/** Signup conflict — username or email already taken (intentionally vague for enumeration prevention). */
+export const ERROR_SIGNUP_CONFLICT = 'signup_conflict';
+/** Invite not found (for delete operations). */
+export const ERROR_INVITE_NOT_FOUND = 'invite_not_found';
+/** Invite must have at least an email or username. */
+export const ERROR_INVITE_MISSING_IDENTIFIER = 'invite_missing_identifier';
+/** An unclaimed invite already exists for this email or username. */
+export const ERROR_INVITE_DUPLICATE = 'invite_duplicate';
+/** An account already exists with this invite's username. */
+export const ERROR_INVITE_ACCOUNT_EXISTS_USERNAME = 'invite_account_exists_username';
+/** An account already exists with this invite's email. */
+export const ERROR_INVITE_ACCOUNT_EXISTS_EMAIL = 'invite_account_exists_email';
+// --- Admin routes ---
+/** Admin tried to grant a role that is not web-grantable. */
+export const ERROR_ROLE_NOT_WEB_GRANTABLE = 'role_not_web_grantable';
+/** Permit ID not found or not owned by the target actor. */
+export const ERROR_PERMIT_NOT_FOUND = 'permit_not_found';
+/** Query parameter `event_type` is not a valid audit event type. */
+export const ERROR_INVALID_EVENT_TYPE = 'invalid_event_type';
+// --- DB table browser ---
+/** DELETE blocked by a foreign key constraint. */
+export const ERROR_FOREIGN_KEY_VIOLATION = 'foreign_key_violation';
+/** Table name not found in `information_schema`. */
+export const ERROR_TABLE_NOT_FOUND = 'table_not_found';
+/** Table has no primary key constraint (cannot delete by PK). */
+export const ERROR_TABLE_NO_PRIMARY_KEY = 'table_no_primary_key';
+/** Row with the given PK value not found. */
+export const ERROR_ROW_NOT_FOUND = 'row_not_found';
+// --- Standard error shapes ---
+// Using z.looseObject — error responses may carry extra context fields.
+/** Base API error — all JSON error responses have at least `{error: string}`. */
+export const ApiError = z.looseObject({ error: z.string() });
+/**
+ * Input validation error — returned when the request body fails Zod parsing.
+ *
+ * `issues` contains the Zod validation issues for diagnostic display.
+ */
+export const ValidationError = z.looseObject({
+    error: z.string(),
+    issues: z.array(z.looseObject({
+        code: z.string(),
+        message: z.string(),
+        path: z.array(z.union([z.string(), z.number()])),
+    })),
+});
+/** Permission error — returned by `require_role()` when the required role is missing. */
+export const PermissionError = z.looseObject({
+    error: z.literal(ERROR_INSUFFICIENT_PERMISSIONS),
+    required_role: z.string(),
+});
+/** Keeper credential error — returned by `require_keeper` when credential type is wrong. */
+export const KeeperError = z.looseObject({
+    error: z.literal(ERROR_KEEPER_REQUIRES_DAEMON_TOKEN),
+    credential_type: z.string(),
+});
+/** Rate limit error — returned when a rate limiter rejects the request. */
+export const RateLimitError = z.looseObject({
+    error: z.literal(ERROR_RATE_LIMIT_EXCEEDED),
+    retry_after: z.number(),
+});
+/** Payload too large error — returned when the request body exceeds the size limit. */
+export const PayloadTooLargeError = z.looseObject({
+    error: z.literal(ERROR_PAYLOAD_TOO_LARGE),
+});
+/** Foreign key violation error — returned when a delete is blocked by references. */
+export const ForeignKeyError = z.looseObject({
+    error: z.literal(ERROR_FOREIGN_KEY_VIOLATION),
+});
+/**
+ * Derive error schemas from a route's auth requirement, input schema, and rate limit config.
+ *
+ * Returns the error schemas that middleware will auto-produce for this route.
+ * Route handlers can declare additional error schemas via `RouteSpec.errors`;
+ * explicit entries override auto-derived ones for the same status code.
+ *
+ * Derivation rules:
+ * - **Has input schema** (non-null) or **has params schema** or **has query schema**: 400 (validation error with issues)
+ * - **auth: authenticated**: 401
+ * - **auth: role**: 401 + 403 (with `required_role`)
+ * - **auth: keeper**: 401 + 403 (keeper-specific)
+ * - **rate_limit**: 429 (rate limit exceeded with `retry_after`)
+ *
+ * @param auth - the route's auth requirement
+ * @param has_input - whether the route has a non-null input schema
+ * @param has_params - whether the route has a params schema
+ * @param has_query - whether the route has a query schema
+ * @param rate_limit - the rate limit key type, if any
+ * @returns error schemas keyed by HTTP status code
+ */
+export const derive_error_schemas = (auth, has_input, has_params = false, has_query = false, rate_limit) => {
+    const errors = {};
+    if (has_input || has_params || has_query) {
+        errors[400] = ValidationError;
+    }
+    switch (auth.type) {
+        case 'none':
+            break;
+        case 'authenticated':
+            errors[401] = ApiError;
+            break;
+        case 'role':
+            errors[401] = ApiError;
+            errors[403] = PermissionError;
+            break;
+        case 'keeper':
+            errors[401] = ApiError;
+            errors[403] = KeeperError;
+            break;
+    }
+    if (rate_limit) {
+        errors[429] = RateLimitError;
+    }
+    return errors;
+};

package/dist/http/middleware_spec.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Middleware spec type — named middleware layer definition.
+ *
+ * Separated from `route_spec.ts` so middleware modules can import this
+ * type without creating an upward dependency on routes.
+ *
+ * @module
+ */
+import type { MiddlewareHandler } from 'hono';
+import type { RouteErrorSchemas } from './error_schemas.js';
+/** A named middleware layer. */
+export interface MiddlewareSpec {
+    name: string;
+    path: string;
+    handler: MiddlewareHandler;
+    /** Error response schemas this middleware can produce, keyed by HTTP status code. */
+    errors?: RouteErrorSchemas;
+}
+//# sourceMappingURL=middleware_spec.d.ts.map

package/dist/http/middleware_spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware_spec.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/middleware_spec.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAE5C,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,oBAAoB,CAAC;AAE1D,gCAAgC;AAChC,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,iBAAiB,CAAC;IAC3B,qFAAqF;IACrF,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC3B"}

package/dist/http/middleware_spec.js

@@ -0,0 +1,9 @@
+/**
+ * Middleware spec type — named middleware layer definition.
+ *
+ * Separated from `route_spec.ts` so middleware modules can import this
+ * type without creating an upward dependency on routes.
+ *
+ * @module
+ */
+export {};

package/dist/http/origin.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Request source verification middleware for API protection.
+ *
+ * Verifies requests are coming from expected origins/referers.
+ * CSRF protection is provided by `SameSite: strict` on session cookies
+ * (see `session_middleware.ts`). This module provides origin allowlisting
+ * for locally-running services — preventing untrusted websites from
+ * making requests as the user browses the web.
+ *
+ * @module
+ */
+import type { Handler } from 'hono';
+/**
+ * Parses ALLOWED_ORIGINS env var into regex matchers for request source verification.
+ * Origin allowlisting for locally-running services — not the CSRF layer
+ * (that's `SameSite: strict` on session cookies).
+ *
+ * Accepts comma-separated patterns with limited wildcards:
+ * - Exact origins: `https://api.fuz.dev`
+ * - Wildcard subdomains: `https://*.fuz.dev` (matches exactly one subdomain level)
+ * - Multiple wildcards: `https://*.staging.*.fuz.dev` (for deep subdomains)
+ * - Wildcard ports: `http://localhost:*` (matches any port or no port)
+ * - IPv6 addresses: `http://[::1]:3000`, `https://[2001:db8::1]`
+ * - Combined: `https://*.fuz.dev:*`
+ *
+ * Examples:
+ * - `http://localhost:3000,https://prod.fuz.dev`
+ * - `https://*.api.fuz.dev,http://127.0.0.1:*`
+ * - `http://[::1]:*,https://*.*.corp.fuz.dev:*`
+ *
+ * @throws if any individual pattern is invalid (missing protocol, partial wildcards, etc.)
+ */
+export declare const parse_allowed_origins: (env_value: string | undefined) => Array<RegExp>;
+/**
+ * Tests if a request source (origin or referer) matches any of the allowed patterns.
+ * Pattern matching is case-insensitive for domains (as per web standards).
+ */
+export declare const should_allow_origin: (origin: string, allowed_patterns: Array<RegExp>) => boolean;
+/**
+ * Middleware that verifies the request source against an allowlist.
+ *
+ * Origin allowlisting (not the CSRF layer — that's `SameSite: strict` cookies) that:
+ * - Checks the Origin header first (if present)
+ * - Falls back to Referer header (if no Origin)
+ * - Allows requests without Origin/Referer headers (direct access, curl, etc.)
+ *
+ * This is useful for:
+ * - Protecting locally-running services from being called by
+ *   untrusted websites as the user browses the web
+ * - Restricting which domains can make requests to your API
+ * - Preventing embedding of your service in unexpected sites
+ * - Basic source verification for locally-running services
+ *
+ * @param allowed_patterns - array of compiled regex patterns from parse_allowed_origins
+ */
+export declare const verify_request_source: (allowed_patterns: Array<RegExp>) => Handler;
+//# sourceMappingURL=origin.d.ts.map

package/dist/http/origin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"origin.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/origin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,MAAM,CAAC;AAIlC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,qBAAqB,GAAI,WAAW,MAAM,GAAG,SAAS,KAAG,KAAK,CAAC,MAAM,CAO5E,CAAC;AAEP;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ,MAAM,EAAE,kBAAkB,KAAK,CAAC,MAAM,CAAC,KAAG,OACzC,CAAC;AAE9C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,GAChC,kBAAkB,KAAK,CAAC,MAAM,CAAC,KAAG,OA2BlC,CAAC"}

package/dist/http/origin.js

@@ -0,0 +1,207 @@
+/**
+ * Request source verification middleware for API protection.
+ *
+ * Verifies requests are coming from expected origins/referers.
+ * CSRF protection is provided by `SameSite: strict` on session cookies
+ * (see `session_middleware.ts`). This module provides origin allowlisting
+ * for locally-running services — preventing untrusted websites from
+ * making requests as the user browses the web.
+ *
+ * @module
+ */
+import { escape_regexp } from '@fuzdev/fuz_util/regexp.js';
+import { ERROR_FORBIDDEN_ORIGIN, ERROR_FORBIDDEN_REFERER } from './error_schemas.js';
+/**
+ * Parses ALLOWED_ORIGINS env var into regex matchers for request source verification.
+ * Origin allowlisting for locally-running services — not the CSRF layer
+ * (that's `SameSite: strict` on session cookies).
+ *
+ * Accepts comma-separated patterns with limited wildcards:
+ * - Exact origins: `https://api.fuz.dev`
+ * - Wildcard subdomains: `https://*.fuz.dev` (matches exactly one subdomain level)
+ * - Multiple wildcards: `https://*.staging.*.fuz.dev` (for deep subdomains)
+ * - Wildcard ports: `http://localhost:*` (matches any port or no port)
+ * - IPv6 addresses: `http://[::1]:3000`, `https://[2001:db8::1]`
+ * - Combined: `https://*.fuz.dev:*`
+ *
+ * Examples:
+ * - `http://localhost:3000,https://prod.fuz.dev`
+ * - `https://*.api.fuz.dev,http://127.0.0.1:*`
+ * - `http://[::1]:*,https://*.*.corp.fuz.dev:*`
+ *
+ * @throws if any individual pattern is invalid (missing protocol, partial wildcards, etc.)
+ */
+export const parse_allowed_origins = (env_value) => env_value
+    ? env_value
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map(origin_pattern_to_regexp)
+    : [];
+/**
+ * Tests if a request source (origin or referer) matches any of the allowed patterns.
+ * Pattern matching is case-insensitive for domains (as per web standards).
+ */
+export const should_allow_origin = (origin, allowed_patterns) => allowed_patterns.some((p) => p.test(origin));
+/**
+ * Middleware that verifies the request source against an allowlist.
+ *
+ * Origin allowlisting (not the CSRF layer — that's `SameSite: strict` cookies) that:
+ * - Checks the Origin header first (if present)
+ * - Falls back to Referer header (if no Origin)
+ * - Allows requests without Origin/Referer headers (direct access, curl, etc.)
+ *
+ * This is useful for:
+ * - Protecting locally-running services from being called by
+ *   untrusted websites as the user browses the web
+ * - Restricting which domains can make requests to your API
+ * - Preventing embedding of your service in unexpected sites
+ * - Basic source verification for locally-running services
+ *
+ * @param allowed_patterns - array of compiled regex patterns from parse_allowed_origins
+ */
+export const verify_request_source = (allowed_patterns) => (c, next) => {
+    // Check origin header (preferred, sent by browsers for CORS requests).
+    // Uses !== undefined so empty-string Origin headers are treated as
+    // present (abnormal, checked against allowlist — empty string never matches).
+    const origin = c.req.header('origin');
+    if (origin !== undefined) {
+        if (!should_allow_origin(origin, allowed_patterns)) {
+            return c.json({ error: ERROR_FORBIDDEN_ORIGIN }, 403);
+        }
+        return next();
+    }
+    // Check referer header (fallback for some requests like gets and navigation).
+    // Same !== undefined check as origin.
+    const referer = c.req.header('referer');
+    if (referer !== undefined) {
+        const referer_origin = extract_origin_from_referer(referer);
+        if (!should_allow_origin(referer_origin, allowed_patterns)) {
+            return c.json({ error: ERROR_FORBIDDEN_REFERER }, 403);
+        }
+        return next();
+    }
+    // No origin or referer - direct access (curl, CLI, etc.)
+    // Allow through since token auth is the primary security control.
+    return next();
+};
+/**
+ * Converts origin patterns with wildcards to regex patterns.
+ *
+ * Pattern format: protocol://hostname[:port]
+ *
+ * Wildcard support:
+ * - Subdomain wildcards: `*.fuz.dev` matches `sub.fuz.dev` (NOT `fuz.dev`)
+ * - Multiple wildcards: `*.*.fuz.dev` matches `api.staging.fuz.dev`
+ * - Port wildcards: `fuz.dev:*` matches any port or no port
+ * - IPv6 support: `[::1]`, `[2001:db8::1]` (no wildcards in IPv6)
+ *
+ * Restrictions:
+ * - No paths allowed (origins don't include paths)
+ * - Wildcards must be complete labels (`*.fuz.dev`, not `*fuz.dev`)
+ * - No wildcards in IPv6 addresses
+ * - Port wildcards must be `:*` exactly
+ *
+ * Note: Patterns are normalized via URL constructor. IPv4-mapped IPv6 addresses
+ * like `[::ffff:127.0.0.1]` will be normalized to `[::ffff:7f00:1]`. IPv6 zone
+ * identifiers (e.g., `%eth0`) are not supported.
+ *
+ * @throws if pattern format is invalid
+ */
+const origin_pattern_to_regexp = (pattern) => {
+    // Quick validation: no paths, query strings, or fragments allowed
+    const protocol_idx = pattern.indexOf('://');
+    if (protocol_idx === -1) {
+        throw new Error(`Invalid origin pattern: ${pattern}`);
+    }
+    const after_protocol = pattern.slice(protocol_idx + 3);
+    if (/[/?#]/.test(after_protocol)) {
+        throw new Error(`Paths not allowed in origin patterns: ${pattern}`);
+    }
+    // Check for wildcards in IPv6 before URL parsing (URL rejects these with unhelpful error)
+    const ipv6_match = /^\[([^\]]+)\]/.exec(after_protocol);
+    if (ipv6_match?.[1]?.includes('*')) {
+        throw new Error(`Wildcards not allowed in IPv6 addresses: ${pattern}`);
+    }
+    // Handle port wildcard - must be at the end
+    let port_wildcard = false;
+    let parse_pattern = pattern;
+    if (pattern.endsWith(':*')) {
+        port_wildcard = true;
+        parse_pattern = pattern.slice(0, -2);
+    }
+    // Parse with URL constructor for robust handling of protocol, hostname, port, IPv6
+    let url;
+    try {
+        url = new URL(parse_pattern);
+    }
+    catch {
+        throw new Error(`Invalid origin pattern: ${pattern}`);
+    }
+    // Validate protocol is http or https
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`Invalid origin pattern: ${pattern}`);
+    }
+    const hostname = url.hostname;
+    const is_ipv6 = hostname.startsWith('[');
+    // For regular hostnames, wildcards must be complete labels
+    if (!is_ipv6) {
+        for (const label of hostname.split('.')) {
+            if (label.includes('*') && label !== '*') {
+                throw new Error(`Wildcards must be complete labels (e.g., *.fuz.dev, not *fuz.dev): ${pattern}`);
+            }
+        }
+    }
+    // Build regex pattern
+    let regex_pattern = '^' + escape_regexp(url.protocol) + '//';
+    // Handle hostname
+    if (is_ipv6) {
+        // IPv6 address - URL.hostname includes brackets
+        regex_pattern += escape_regexp(hostname);
+    }
+    else {
+        // Regular hostname - process wildcards
+        const labels = hostname.split('.');
+        regex_pattern += labels
+            .map((label) => (label === '*' ? '[^./:]+' : escape_regexp(label)))
+            .join('\\.');
+    }
+    // Handle port
+    if (port_wildcard) {
+        // Optional port (matches both with and without port)
+        regex_pattern += '(:\\d+)?';
+    }
+    else {
+        // URL normalizes default ports (80 for HTTP, 443 for HTTPS) away,
+        // so check original pattern for explicit port when url.port is empty
+        let port = url.port;
+        if (!port) {
+            const port_match = /:(\d+)$/.exec(parse_pattern);
+            if (port_match?.[1]) {
+                port = port_match[1];
+            }
+        }
+        if (port) {
+            regex_pattern += ':' + escape_regexp(port);
+        }
+    }
+    regex_pattern += '$';
+    // Case-insensitive matching (web standards specify domains are case-insensitive)
+    return new RegExp(regex_pattern, 'i');
+};
+/**
+ * Extracts the origin from a referer URL, removing the path, query string, and fragment.
+ *
+ * @param referer - the referer URL (e.g., `https://fuz.dev/path?query#hash`)
+ * @returns the origin part (e.g., `https://fuz.dev`)
+ */
+const extract_origin_from_referer = (referer) => {
+    try {
+        return new URL(referer).origin;
+    }
+    catch {
+        // If URL parsing fails, return the original string
+        // (it will likely fail pattern matching anyway)
+        return referer;
+    }
+};