@facilis.dev/auth 0.0.0-stage → 0.1.0

package/dist/roles.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Auth context attached to requests once a session is validated (contract §4.1/§6).
+ *
+ * It deliberately carries no tenant (D-040): the tenant is the deployment's, resolved from
+ * FACILIS_TENANT_ID for every request, so a session can neither widen nor change the RLS scope.
+ */
+export interface AuthContext {
+    readonly userId: string;
+    readonly roles: readonly string[];
+    readonly permissions: readonly string[];
+    /**
+     * SHA-256 (hex) of the session id (D-099): the sudo audit log correlates a request with
+     * the session it ran under without ever storing the value of the cookie.
+     */
+    readonly sessionHash?: string;
+    /**
+     * Which credential produced this context (V3a): a browser session or a programmatic API
+     * bearer token. Audit/logging code reads it to separate machine traffic from human sessions.
+     */
+    readonly via?: "session" | "bearer";
+}
+/** Shape of `facilis.config.ts`'s `auth` block that @facilis.dev/auth needs. */
+export interface AuthConfig {
+    readonly permissions: readonly string[];
+    readonly roles: Readonly<Record<string, readonly string[]>>;
+    readonly defaultRole: string;
+    readonly sessionDurationMs: number;
+}
+/**
+ * Expands app roles into concrete permissions, deterministically: roles keep their input
+ * order, permissions keep config order, duplicates collapse to the first occurrence.
+ * Unknown roles (e.g. a stale `user_roles` row) contribute nothing.
+ */
+export declare function expandRoles(roles: readonly string[], config: AuthConfig): string[];
+/**
+ * Route RBAC check (contract §4.4): `[]` requires nothing (public route), a non-empty
+ * list requires at least one match, and null means no session. A literal "*" permission
+ * on the subject grants everything as a safety net for hand-built contexts.
+ */
+export declare function hasPermission(subject: Pick<AuthContext, "permissions"> | null, permission: string | readonly string[]): boolean;

package/dist/roles.js

@@ -0,0 +1,46 @@
+const WILDCARD = "*";
+/**
+ * Expands app roles into concrete permissions, deterministically: roles keep their input
+ * order, permissions keep config order, duplicates collapse to the first occurrence.
+ * Unknown roles (e.g. a stale `user_roles` row) contribute nothing.
+ */
+export function expandRoles(roles, config) {
+    const expanded = [];
+    const seen = new Set();
+    const add = (permission) => {
+        if (seen.has(permission))
+            return;
+        seen.add(permission);
+        expanded.push(permission);
+    };
+    for (const role of roles) {
+        const declared = config.roles[role];
+        if (declared === undefined)
+            continue;
+        for (const permission of declared) {
+            if (permission === WILDCARD) {
+                for (const granted of config.permissions)
+                    add(granted);
+            }
+            else {
+                add(permission);
+            }
+        }
+    }
+    return expanded;
+}
+/**
+ * Route RBAC check (contract §4.4): `[]` requires nothing (public route), a non-empty
+ * list requires at least one match, and null means no session. A literal "*" permission
+ * on the subject grants everything as a safety net for hand-built contexts.
+ */
+export function hasPermission(subject, permission) {
+    const required = typeof permission === "string" ? [permission] : permission;
+    if (required.length === 0)
+        return true;
+    if (subject === null)
+        return false;
+    if (subject.permissions.includes(WILDCARD))
+        return true;
+    return required.some((candidate) => subject.permissions.includes(candidate));
+}

package/dist/seed.d.ts

@@ -0,0 +1,28 @@
+import type { PolicyScopedDatabase } from "@facilis.dev/db";
+import type { AuthConfig } from "./roles.js";
+export interface SeedEntry {
+    readonly role: string;
+    readonly permission: string;
+}
+/**
+ * Pure projection of `config.auth.roles` into `role_permissions` rows (SPEC §5.3/§8.4.2).
+ * Wildcards stay literal ("*") exactly as the reference seed shows; the table is written
+ * only at migration time, never at runtime.
+ */
+export declare function seedFromConfig(config: AuthConfig): SeedEntry[];
+/**
+ * Deterministic, idempotent SQL for the migration/seed step: roles first, then
+ * role_permissions, every statement guarded by ON CONFLICT DO NOTHING.
+ */
+export declare function seedStatements(config: AuthConfig): string[];
+/**
+ * Grants `admin` to the user whose email matches FACILIS_INITIAL_ADMIN (SPEC §8.4.3).
+ *
+ * The email alone is not a credential: it is public and the registration route is public, so
+ * the promotion ALSO requires the operator's one-time FACILIS_INITIAL_ADMIN_TOKEN (D-150).
+ * Both variables must be set; a missing token fails closed, the token is compared in constant
+ * time, and the promotion happens only while no admin exists yet, so a deploy that keeps the
+ * token configured after bootstrap cannot be re-triggered. Accepts a user id or email; returns
+ * false when any condition fails.
+ */
+export declare function registerInitialAdmin(db: PolicyScopedDatabase, userIdOrEmail: string, bootstrapToken?: string): Promise<boolean>;

package/dist/seed.js

@@ -0,0 +1,115 @@
+import { eq, sql } from "drizzle-orm";
+import { constantTimeEqual, sha256Hex } from "./crypto.js";
+import { normalizeEmail } from "./email.js";
+import { userRoles, users } from "./tables.js";
+const INITIAL_ADMIN_ROLE = "admin";
+/**
+ * Pure projection of `config.auth.roles` into `role_permissions` rows (SPEC §5.3/§8.4.2).
+ * Wildcards stay literal ("*") exactly as the reference seed shows; the table is written
+ * only at migration time, never at runtime.
+ */
+export function seedFromConfig(config) {
+    const entries = [];
+    const seen = new Set();
+    for (const [role, permissions] of Object.entries(config.roles)) {
+        for (const permission of permissions) {
+            const key = `${role}\u0000${permission}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            entries.push({ role, permission });
+        }
+    }
+    return entries;
+}
+/**
+ * Deterministic, idempotent SQL for the migration/seed step: roles first, then
+ * role_permissions, every statement guarded by ON CONFLICT DO NOTHING.
+ */
+export function seedStatements(config) {
+    const statements = [];
+    for (const role of Object.keys(config.roles)) {
+        statements.push(`INSERT INTO roles (name) VALUES (${sqlLiteral(role)}) ON CONFLICT DO NOTHING;`);
+    }
+    for (const { role, permission } of seedFromConfig(config)) {
+        statements.push(`INSERT INTO role_permissions (role, permission) VALUES (${sqlLiteral(role)}, ${sqlLiteral(permission)}) ON CONFLICT DO NOTHING;`);
+    }
+    return statements;
+}
+/**
+ * Grants `admin` to the user whose email matches FACILIS_INITIAL_ADMIN (SPEC §8.4.3).
+ *
+ * The email alone is not a credential: it is public and the registration route is public, so
+ * the promotion ALSO requires the operator's one-time FACILIS_INITIAL_ADMIN_TOKEN (D-150).
+ * Both variables must be set; a missing token fails closed, the token is compared in constant
+ * time, and the promotion happens only while no admin exists yet, so a deploy that keeps the
+ * token configured after bootstrap cannot be re-triggered. Accepts a user id or email; returns
+ * false when any condition fails.
+ */
+export async function registerInitialAdmin(db, userIdOrEmail, bootstrapToken) {
+    const expected = readInitialAdminEmail();
+    if (expected === null)
+        return false;
+    const expectedToken = readInitialAdminToken();
+    if (expectedToken === null || bootstrapToken === undefined)
+        return false;
+    if (!(await tokenMatches(bootstrapToken, expectedToken)))
+        return false;
+    // One-time: an admin already assigned means bootstrap is over, even if the env stays set.
+    if (await hasAdmin(db))
+        return false;
+    const user = await findUser(db, userIdOrEmail.trim());
+    if (user === null)
+        return false;
+    // Emails compare in canonical form: a case variant of the configured address is not the
+    // configured address (the unique lower(email) index makes the two the same account, D-150).
+    if (normalizeEmail(user.email) !== expected)
+        return false;
+    await db
+        .insert(userRoles)
+        .values({ userId: user.id, role: INITIAL_ADMIN_ROLE })
+        .onConflictDoNothing();
+    return true;
+}
+function readInitialAdminEmail() {
+    const configured = process.env.FACILIS_INITIAL_ADMIN?.trim();
+    return configured === undefined || configured.length === 0 ? null : normalizeEmail(configured);
+}
+function readInitialAdminToken() {
+    const configured = process.env.FACILIS_INITIAL_ADMIN_TOKEN?.trim();
+    return configured === undefined || configured.length === 0 ? null : configured;
+}
+/**
+ * Hash-then-compare keeps the comparison independent of the two input lengths, so a wrong
+ * token leaks neither its length nor the index of the first wrong character.
+ */
+async function tokenMatches(provided, expected) {
+    const [left, right] = await Promise.all([sha256Hex(provided), sha256Hex(expected)]);
+    return constantTimeEqual(new TextEncoder().encode(left), new TextEncoder().encode(right));
+}
+async function hasAdmin(db) {
+    const rows = await db
+        .select({ role: userRoles.role })
+        .from(userRoles)
+        .where(eq(userRoles.role, INITIAL_ADMIN_ROLE))
+        .limit(1);
+    return rows.length > 0;
+}
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+async function findUser(db, userIdOrEmail) {
+    const rows = UUID_PATTERN.test(userIdOrEmail)
+        ? await db
+            .select({ id: users.id, email: users.email })
+            .from(users)
+            .where(eq(users.id, userIdOrEmail))
+            .limit(1)
+        : await db
+            .select({ id: users.id, email: users.email })
+            .from(users)
+            .where(sql `lower(${users.email}) = ${normalizeEmail(userIdOrEmail)}`)
+            .limit(1);
+    return rows[0] ?? null;
+}
+function sqlLiteral(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}

package/dist/session.d.ts

@@ -0,0 +1,66 @@
+import { type FacilisDb, type PolicyScopedDatabase } from "@facilis.dev/db";
+import { type AuthConfig } from "./roles.js";
+import { type AuthUser, type SessionRow } from "./tables.js";
+/** Cookie name fixed by contract §4.4; HttpOnly/Path=/SameSite=Lax/Secure-in-prod. The cookie
+ * carries the raw 32-byte token; the sessions row stores only its SHA-256 (D-144). */
+export declare const SESSION_COOKIE_NAME = "facilis_session";
+export interface CreateSessionOptions {
+    readonly ttlMs?: number;
+}
+export interface ValidatedSession {
+    readonly user: AuthUser;
+    readonly session: SessionRow;
+}
+/** Creates an opaque session row; callers set the cookie themselves (route blueprint). */
+export declare function createSession(db: PolicyScopedDatabase, userId: string, options?: CreateSessionOptions): Promise<{
+    id: string;
+    expiresAt: Date;
+}>;
+/**
+ * Joins the session to its user; expired or unknown sessions yield null.
+ *
+ * Callers pass a policy-scoped client (`runWithPolicyScope`) with app.tenant_id set: users
+ * carries tenant RLS, so an unscoped read as the non-superuser facilis_app role cannot see
+ * the joined user row at all.
+ */
+export declare function validateSession(db: PolicyScopedDatabase, sessionId: string): Promise<ValidatedSession | null>;
+/** Deletes a session row; deleting an unknown id is a no-op. */
+export declare function destroySession(db: PolicyScopedDatabase, sessionId: string): Promise<void>;
+/**
+ * Structural event type: an H3/Nitro event satisfies it without importing h3 here.
+ * `context` stays a plain record because h3's H3EventContext exposes unknown values
+ * through an index signature; middleware writes `context.auth` (AuthContext | null).
+ */
+export type SessionEventContext = Record<string, unknown>;
+export interface SessionEvent {
+    context: SessionEventContext;
+    req: {
+        headers: {
+            get(name: string): string | null;
+        };
+    };
+}
+export interface SessionMiddlewareDeps {
+    /** Database the middleware scopes; the runtime may connect as the facilis_app role. */
+    readonly db: FacilisDb;
+    readonly config: AuthConfig;
+    /** The deployment's tenant; a session whose user row names another one is rejected (D-040). */
+    readonly tenantId: string;
+}
+/**
+ * Builds the `facilis-session` middleware handler. An `Authorization: Bearer` token wins
+ * over the session cookie; otherwise it reads the cookie, then validates the session and
+ * loads app roles inside ONE deployment-tenant policy scope (`runWithPolicyScope`), expands
+ * the roles from config (SPEC §8.4.4) and sets `context.auth` with the auth channel in `via`.
+ *
+ * The scope matters: production connects as the non-superuser facilis_app role, so `users`
+ * is RLS-filtered and an unscoped read cannot see any user row. Running both queries in the
+ * tenant's transaction is what makes sessions work without a privileged client (D-068).
+ */
+export declare function sessionMiddleware(deps: SessionMiddlewareDeps): (event: SessionEvent) => Promise<void>;
+/**
+ * Extracts the token from an `Authorization: Bearer <token>` header. The scheme is
+ * case-insensitive (RFC 7235) and the token is returned verbatim; an empty, absent or
+ * malformed header yields null, i.e. "no bearer auth".
+ */
+export declare function readBearerToken(header: string | null): string | null;

package/dist/session.js

@@ -0,0 +1,161 @@
+import { eq } from "drizzle-orm";
+import { runWithPolicyScope } from "@facilis.dev/db";
+import { validateApiToken } from "./api-clients.js";
+import { randomToken, sha256Hex } from "./crypto.js";
+import { expandRoles } from "./roles.js";
+import { sessions, userRoles, users } from "./tables.js";
+/** Cookie name fixed by contract §4.4; HttpOnly/Path=/SameSite=Lax/Secure-in-prod. The cookie
+ * carries the raw 32-byte token; the sessions row stores only its SHA-256 (D-144). */
+export const SESSION_COOKIE_NAME = "facilis_session";
+const DEFAULT_SESSION_TTL_MS = 1000 * 60 * 60 * 24 * 7;
+/** Creates an opaque session row; callers set the cookie themselves (route blueprint). */
+export async function createSession(db, userId, options = {}) {
+    // A service account exists only for machine credentials: minting a cookie session for one
+    // would make it loggable in a browser, so refuse here even if a caller missed the flag.
+    const serviceAccount = await db
+        .select({ isService: users.isService })
+        .from(users)
+        .where(eq(users.id, userId))
+        .limit(1);
+    if (serviceAccount[0]?.isService === true) {
+        throw new Error("createSession: service accounts cannot log in");
+    }
+    const id = randomToken(32);
+    const expiresAt = new Date(Date.now() + (options.ttlMs ?? DEFAULT_SESSION_TTL_MS));
+    // The row key is the SHA-256 of the cookie value: the raw id is the credential and never
+    // reaches the database, so a SELECT on sessions (RLS-scoped, tenant-visible) cannot be
+    // replayed as a session. The cookie keeps the raw value; lookups hash it again.
+    await db.insert(sessions).values({ id: await sha256Hex(id), userId, expiresAt });
+    return { id, expiresAt };
+}
+/**
+ * Joins the session to its user; expired or unknown sessions yield null.
+ *
+ * Callers pass a policy-scoped client (`runWithPolicyScope`) with app.tenant_id set: users
+ * carries tenant RLS, so an unscoped read as the non-superuser facilis_app role cannot see
+ * the joined user row at all.
+ */
+export async function validateSession(db, sessionId) {
+    // Rows hold sha256(cookie id): the caller passes the raw cookie and the lookup hashes it.
+    const rows = await db
+        .select({
+        session: sessions,
+        user: {
+            id: users.id,
+            email: users.email,
+            tenantId: users.tenantId,
+            createdAt: users.createdAt,
+        },
+        isService: users.isService,
+    })
+        .from(sessions)
+        .innerJoin(users, eq(sessions.userId, users.id))
+        .where(eq(sessions.id, await sha256Hex(sessionId)))
+        .limit(1);
+    const found = rows[0];
+    if (found === undefined)
+        return null;
+    // Defense in depth: a service account never validates a cookie session, even one inserted
+    // before createSession started refusing them.
+    if (found.isService)
+        return null;
+    if (found.session.expiresAt.getTime() <= Date.now())
+        return null;
+    return { user: found.user, session: found.session };
+}
+/** Deletes a session row; deleting an unknown id is a no-op. */
+export async function destroySession(db, sessionId) {
+    // Deleting an unknown id stays a no-op; the stored key is the hash of the cookie value.
+    await db.delete(sessions).where(eq(sessions.id, await sha256Hex(sessionId)));
+}
+/**
+ * Builds the `facilis-session` middleware handler. An `Authorization: Bearer` token wins
+ * over the session cookie; otherwise it reads the cookie, then validates the session and
+ * loads app roles inside ONE deployment-tenant policy scope (`runWithPolicyScope`), expands
+ * the roles from config (SPEC §8.4.4) and sets `context.auth` with the auth channel in `via`.
+ *
+ * The scope matters: production connects as the non-superuser facilis_app role, so `users`
+ * is RLS-filtered and an unscoped read cannot see any user row. Running both queries in the
+ * tenant's transaction is what makes sessions work without a privileged client (D-068).
+ */
+export function sessionMiddleware(deps) {
+    return async (event) => {
+        const bearerToken = readBearerToken(event.req.headers.get("authorization"));
+        if (bearerToken !== null) {
+            // A bearer request never falls back to the cookie: the client chose token auth, so an
+            // invalid token is anonymous rather than a browser session. The raw token is only ever
+            // hashed here — it must never be logged or stored (D-099).
+            event.context.auth = await runWithPolicyScope(deps.db, { tenantId: deps.tenantId }, async (tx) => {
+                const validated = await validateApiToken(tx, bearerToken);
+                if (validated === null)
+                    return null;
+                return {
+                    userId: validated.userId,
+                    roles: [validated.role],
+                    permissions: expandRoles([validated.role], deps.config),
+                    sessionHash: validated.tokenHash,
+                    via: "bearer",
+                };
+            });
+            return;
+        }
+        const sessionId = readCookie(event.req.headers.get("cookie"), SESSION_COOKIE_NAME);
+        if (sessionId === null) {
+            event.context.auth = null;
+            return;
+        }
+        const auth = await runWithPolicyScope(deps.db, { tenantId: deps.tenantId }, async (tx) => {
+            const found = await validateSession(tx, sessionId);
+            if (found === null)
+                return null;
+            // The tenant is the deployment's, never the session's (D-040). RLS already hides another
+            // tenant's user row from the lookup; this explicit check keeps the rule even on a
+            // connection where RLS would not apply (defense in depth).
+            if (found.user.tenantId !== deps.tenantId)
+                return null;
+            const roles = await loadUserRoles(tx, found.user.id);
+            return {
+                userId: found.user.id,
+                roles,
+                permissions: expandRoles(roles, deps.config),
+            };
+        });
+        // Only a valid session gets a hash: the audit trail correlates requests with a session
+        // without ever storing the cookie value (D-099).
+        event.context.auth =
+            auth === null ? null : { ...auth, sessionHash: await sha256Hex(sessionId), via: "session" };
+    };
+}
+async function loadUserRoles(db, userId) {
+    const rows = await db
+        .select({ role: userRoles.role })
+        .from(userRoles)
+        .where(eq(userRoles.userId, userId));
+    return rows.map((row) => row.role);
+}
+/**
+ * Extracts the token from an `Authorization: Bearer <token>` header. The scheme is
+ * case-insensitive (RFC 7235) and the token is returned verbatim; an empty, absent or
+ * malformed header yields null, i.e. "no bearer auth".
+ */
+export function readBearerToken(header) {
+    if (header === null || header.length === 0)
+        return null;
+    const match = /^Bearer[ \t]+(.+)$/i.exec(header.trim());
+    const token = match?.[1]?.trim();
+    return token === undefined || token.length === 0 ? null : token;
+}
+function readCookie(header, name) {
+    if (header === null || header.length === 0)
+        return null;
+    for (const part of header.split(";")) {
+        const separator = part.indexOf("=");
+        if (separator === -1)
+            continue;
+        if (part.slice(0, separator).trim() !== name)
+            continue;
+        const value = part.slice(separator + 1).trim();
+        return value.length === 0 ? null : value;
+    }
+    return null;
+}

package/dist/sso/contracts.d.ts

@@ -0,0 +1,52 @@
+import type { PolicyScopedDatabase } from "@facilis.dev/db";
+/**
+ * Structural contracts shared by the SSO modules (D-120).
+ *
+ * @facilis.dev/core depends on @facilis.dev/auth (route.ts imports the RBAC helpers), so auth cannot
+ * import core without a package cycle. A system elevation is therefore described structurally:
+ * `ctx.system` from `defineAuthorizedHandler` satisfies {@link SystemRunner} without auth
+ * owning a copy of the core type.
+ */
+/** What a system elevation must say about itself; all fields are audited (D-099). */
+export interface SystemElevationOptions {
+    readonly actor: `system:${string}`;
+    readonly operation: string;
+    readonly reason: string;
+    /** Non-empty subset of the route's `dbTables`. */
+    readonly tables: readonly string[];
+}
+/** The audited system elevation passed into the SSO flow: never a raw database client. */
+export type SystemRunner = <T>(options: SystemElevationOptions, fn: (systemDb: PolicyScopedDatabase) => Promise<T>) => Promise<T>;
+/** The identity an IdP asserts: the key, the email and whether that email is verified. */
+export interface IdentityClaims {
+    readonly provider: string;
+    readonly subject: string;
+    readonly email: string;
+    readonly emailVerified: boolean;
+}
+/** The audit input subset the SSO flow writes through `ctx.log.audit` (D-119). */
+export interface SsoAuditInput {
+    readonly operation: string;
+    readonly outcome?: "succeeded" | "failed";
+    readonly errorCode?: string;
+    readonly reason?: string;
+    readonly tables?: readonly string[];
+    readonly details?: Record<string, unknown>;
+}
+/** A narrower audit sink: `ctx.log.audit` satisfies it structurally. */
+export type SsoAudit = (input: SsoAuditInput) => void;
+/** The subset of the Fetch API the OAuth/OIDC/OAuth2 HTTP calls need (no Node dependency). */
+export interface FetchInit {
+    readonly method?: string;
+    readonly headers?: Record<string, string>;
+    readonly body?: string;
+}
+export interface FetchResponse {
+    readonly ok: boolean;
+    readonly status: number;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}
+export type FetchLike = (url: string, init?: FetchInit) => Promise<FetchResponse>;
+/** The runtime fetch, narrowed to {@link FetchLike}; tests inject their own. */
+export declare function runtimeFetch(): FetchLike;

package/dist/sso/contracts.js

@@ -0,0 +1,8 @@
+/** The runtime fetch, narrowed to {@link FetchLike}; tests inject their own. */
+export function runtimeFetch() {
+    const candidate = globalThis.fetch;
+    if (typeof candidate !== "function") {
+        throw new Error("facilis: the runtime has no fetch implementation for SSO");
+    }
+    return candidate;
+}

package/dist/sso/errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Safe machine codes for the SSO namespace (D-120).
+ *
+ * The browser is redirected to `failureRedirect?sso_error=<code>`; an internal message, a token,
+ * an authorization code or a SAML payload never reaches the client. Callers log the cause
+ * server-side through `ctx.log` and expose only the code.
+ */
+export declare const SSO_ERROR_CODES: readonly ["sso_provider_unknown", "sso_provider_unavailable", "sso_state_invalid", "sso_exchange_failed", "sso_identity_invalid", "sso_email_unverified", "sso_email_conflict", "sso_account_not_found", "sso_internal_error"];
+export type SsoErrorCode = (typeof SSO_ERROR_CODES)[number];
+/** Thrown inside the flow; the route maps it to a redirect code, never to its message. */
+export declare class SsoError extends Error {
+    readonly code: SsoErrorCode;
+    constructor(code: SsoErrorCode, message?: string, options?: ErrorOptions);
+}
+export declare function isSsoError(error: unknown): error is SsoError;
+/** Normalises any thrown value to a safe code; an unexpected failure is `sso_internal_error`. */
+export declare function ssoErrorCode(error: unknown): SsoErrorCode;
+/**
+ * Appends `sso_error=<code>` to the configured failure redirect, keeping its existing query
+ * string and fragment-free path. The redirect is same-origin by config validation (D-120).
+ */
+export declare function failureRedirectPath(failureRedirect: string, code: SsoErrorCode): string;

package/dist/sso/errors.js

@@ -0,0 +1,45 @@
+/**
+ * Safe machine codes for the SSO namespace (D-120).
+ *
+ * The browser is redirected to `failureRedirect?sso_error=<code>`; an internal message, a token,
+ * an authorization code or a SAML payload never reaches the client. Callers log the cause
+ * server-side through `ctx.log` and expose only the code.
+ */
+export const SSO_ERROR_CODES = [
+    "sso_provider_unknown",
+    "sso_provider_unavailable",
+    "sso_state_invalid",
+    "sso_exchange_failed",
+    "sso_identity_invalid",
+    "sso_email_unverified",
+    // Verified IdP email matched a PASSWORD account that is not verified, in a deployment where
+    // email verification is off: linking it would be account pre-hijacking (SEC-02, D-156).
+    "sso_email_conflict",
+    "sso_account_not_found",
+    "sso_internal_error",
+];
+/** Thrown inside the flow; the route maps it to a redirect code, never to its message. */
+export class SsoError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message ?? code, options);
+        this.name = "SsoError";
+        this.code = code;
+    }
+}
+export function isSsoError(error) {
+    return error instanceof SsoError;
+}
+/** Normalises any thrown value to a safe code; an unexpected failure is `sso_internal_error`. */
+export function ssoErrorCode(error) {
+    return isSsoError(error) ? error.code : "sso_internal_error";
+}
+/**
+ * Appends `sso_error=<code>` to the configured failure redirect, keeping its existing query
+ * string and fragment-free path. The redirect is same-origin by config validation (D-120).
+ */
+export function failureRedirectPath(failureRedirect, code) {
+    const url = new URL(failureRedirect, "http://facilis.invalid");
+    url.searchParams.set("sso_error", code);
+    return `${url.pathname}${url.search}`;
+}

package/dist/sso/identity.d.ts

@@ -0,0 +1,41 @@
+import type { IdentityClaims, SsoAudit, SystemRunner } from "./contracts.js";
+/**
+ * Account linking and JIT provisioning (D-120).
+ *
+ * The identity key is `(provider, subject)`: a changed email never breaks an existing link.
+ * Without a link, the asserted email must be verified before it can match a user, and a user is
+ * only created when the provider's `autoProvision` allows it. Every read/write happens inside the
+ * caller's audited `ctx.system` elevation — never on a raw client (D-099).
+ *
+ * Races are handled with the unique keys the schema already has: `(provider, subject)` for the
+ * identity and `users.email` for the user, both `ON CONFLICT DO NOTHING` followed by a re-read.
+ */
+export declare const IDENTITY_TABLES: readonly ["auth_identities", "users", "user_roles"];
+export interface IdentityProviderPolicy {
+    readonly id: string;
+    readonly autoProvision: boolean;
+    readonly defaultRole?: string;
+}
+export interface ResolveIdentityOptions {
+    /** `config.auth.defaultRole`, used when the provider has no `defaultRole`. */
+    readonly defaultRole: string;
+    /**
+     * `config.auth.verification.enabled` (D-156): with email verification on, a pending password
+     * account is claimed (the IdP just proved the mailbox). With it off, the account was never
+     * meant to be verified, so the link is refused instead of silently resetting its password.
+     */
+    readonly claimUnverifiedPasswordAccount: boolean;
+    readonly audit: SsoAudit;
+}
+export type IdentityOutcome = "existing" | "linked" | "provisioned";
+export interface IdentityResolution {
+    readonly userId: string;
+    readonly outcome: IdentityOutcome;
+}
+/**
+ * Resolves the Facilis user for a verified identity.
+ *
+ * Throws `sso_email_unverified` for an unverified email that has no existing link and
+ * `sso_account_not_found` when provisioning is disabled; both are safe to redirect.
+ */
+export declare function resolveIdentity(system: SystemRunner, claims: IdentityClaims, provider: IdentityProviderPolicy, options: ResolveIdentityOptions, now?: Date): Promise<IdentityResolution>;