@facilis.dev/auth 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 facilis-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,19 @@
-# Temporary Holding Version
+# @facilis.dev/auth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Facilis authentication and RBAC primitives: sessions, role expansion, permission checks.
+
+Part of [Facilis](https://github.com/facilis-dev/facilis), a browser-first low-code framework: the Studio
+runs a generated project in a WebContainer where vite dev is the only dev server
+and Nitro v3 runs as a Vite plugin. Framework contracts live in
+[docs/SPEC.md](https://github.com/facilis-dev/facilis/blob/main/docs/SPEC.md) and architectural decisions in
+[docs/DECISIONS.md](https://github.com/facilis-dev/facilis/blob/main/docs/DECISIONS.md).
+
+```sh
+npm install @facilis.dev/auth
+```
+
+The package publishes its TypeScript sources and its compiled dist/; the exports map
+of the published manifest points at dist/, so Node and bundlers load JavaScript and
+the bundled .d.ts files.
+
+Licensed under the MIT License.

package/dist/api-clients.d.ts

@@ -0,0 +1,71 @@
+import type { PolicyScopedDatabase } from "@facilis.dev/db";
+export interface CreateApiClientInput {
+    readonly name: string;
+    readonly role: string;
+    /** Interactive user who created the client, when the caller knows it. */
+    readonly createdBy?: string | null;
+}
+export interface CreatedApiClient {
+    readonly id: string;
+    readonly clientId: string;
+    /** One-time plaintext secret: never persisted and not recoverable afterwards. */
+    readonly secret: string;
+    readonly name: string;
+    readonly role: string;
+    readonly userId: string;
+}
+/** Management projection of a client: same columns minus `secretHash`, which never leaves. */
+export interface ApiClientSummary {
+    readonly id: string;
+    readonly clientId: string;
+    readonly name: string;
+    readonly role: string;
+    readonly createdAt: Date | null;
+    readonly revokedAt: Date | null;
+    readonly lastUsedAt: Date | null;
+    readonly userId: string;
+}
+export interface IssueApiTokenInput {
+    readonly clientId: string;
+    readonly clientSecret: string;
+    readonly ttlMs: number;
+}
+export interface IssuedApiToken {
+    readonly accessToken: string;
+    readonly expiresAt: Date;
+}
+export interface ValidatedApiToken {
+    readonly userId: string;
+    /** The client's fixed role, not the service user's (empty) interactive roles. */
+    readonly role: string;
+    /** SHA-256 of the raw token: the audit correlation value, safe to log. */
+    readonly tokenHash: string;
+}
+/**
+ * Creates a service user, its role assignment and an API client.
+ *
+ * Callers run this under the audited system identity: the `roles` table is system-only
+ * (D-136) and here it is the migration-time projection of `config.auth.roles`
+ * (`seedFromConfig`), so a role the project never declared is rejected before any row is
+ * written. The service user takes its tenant from the policy-scope GUC, exactly like a
+ * registration insert (D-040).
+ */
+export declare function createApiClient(db: PolicyScopedDatabase, input: CreateApiClientInput): Promise<CreatedApiClient>;
+/** Lists clients for management; the secret hash is never part of the projection. */
+export declare function listApiClients(db: PolicyScopedDatabase): Promise<ApiClientSummary[]>;
+/**
+ * Revokes a client and every token issued to it. Returns false for an unknown id; revoking
+ * twice is a no-op that keeps the first revocation timestamp (it is an audit fact).
+ */
+export declare function revokeApiClient(db: PolicyScopedDatabase, id: string): Promise<boolean>;
+/**
+ * Exchanges a client id + secret for a bearer token. Returns null for an unknown client, a
+ * wrong secret or a revoked client: the caller cannot tell which one failed.
+ */
+export declare function issueApiToken(db: PolicyScopedDatabase, input: IssueApiTokenInput): Promise<IssuedApiToken | null>;
+/**
+ * Validates a raw bearer token: revoked/expired tokens and tokens of a revoked client are
+ * rejected. Refreshing `last_used_at` is a conditional UPDATE, so a burst of requests does
+ * not turn into a burst of writes or race on the same row.
+ */
+export declare function validateApiToken(db: PolicyScopedDatabase, rawToken: string): Promise<ValidatedApiToken | null>;

package/dist/api-clients.js

@@ -0,0 +1,186 @@
+import { and, eq, isNull, lt, or } from "drizzle-orm";
+import { constantTimeEqual, randomToken, sha256Hex } from "./crypto.js";
+import { apiClients, apiTokens, roles, userRoles, users } from "./tables.js";
+/**
+ * Programmatic API clients (V3a): a service user plus a hashed secret, and short-lived
+ * bearer tokens derived from it.
+ *
+ * Nothing secret is ever stored in the clear: the client secret and every access token are
+ * written as SHA-256 hex digests, and the plaintext appears only in the return value of the
+ * call that creates it (a one-time secret, like a password reset). Secrets are compared
+ * through `constantTimeEqual` so verification does not leak the first mismatching byte.
+ */
+/** Public credential prefixes: a leaked value is recognisable to secret scanners. */
+const CLIENT_ID_PREFIX = "fcli_";
+const CLIENT_SECRET_PREFIX = "fsec_";
+const ACCESS_TOKEN_PREFIX = "fat_";
+const CLIENT_ID_BYTES = 24;
+const CLIENT_SECRET_BYTES = 32;
+const ACCESS_TOKEN_BYTES = 32;
+/**
+ * A successful validation stamps `last_used_at` at most once per window instead of on every
+ * request: the column is for operators ("is this client still used?"), not an access log.
+ */
+const LAST_USED_WRITE_WINDOW_MS = 5 * 60 * 1000;
+/**
+ * Creates a service user, its role assignment and an API client.
+ *
+ * Callers run this under the audited system identity: the `roles` table is system-only
+ * (D-136) and here it is the migration-time projection of `config.auth.roles`
+ * (`seedFromConfig`), so a role the project never declared is rejected before any row is
+ * written. The service user takes its tenant from the policy-scope GUC, exactly like a
+ * registration insert (D-040).
+ */
+export async function createApiClient(db, input) {
+    const knownRole = await db
+        .select({ name: roles.name })
+        .from(roles)
+        .where(eq(roles.name, input.role))
+        .limit(1);
+    if (knownRole.length === 0)
+        throw new Error(`createApiClient: unknown role "${input.role}"`);
+    const createdUser = await db
+        .insert(users)
+        .values({
+        email: `service+${globalThis.crypto.randomUUID()}@facilis.invalid`,
+        passwordHash: null,
+        isService: true,
+    })
+        .returning({ id: users.id });
+    const user = createdUser[0];
+    if (user === undefined)
+        throw new Error("createApiClient: service user insert returned no row");
+    await db.insert(userRoles).values({
+        userId: user.id,
+        role: input.role,
+        assignedBy: input.createdBy ?? null,
+    });
+    const clientId = `${CLIENT_ID_PREFIX}${randomToken(CLIENT_ID_BYTES)}`;
+    const secret = `${CLIENT_SECRET_PREFIX}${randomToken(CLIENT_SECRET_BYTES)}`;
+    const createdClient = await db
+        .insert(apiClients)
+        .values({
+        clientId,
+        secretHash: await sha256Hex(secret),
+        name: input.name,
+        role: input.role,
+        userId: user.id,
+        createdBy: input.createdBy ?? null,
+    })
+        .returning({ id: apiClients.id });
+    const client = createdClient[0];
+    if (client === undefined)
+        throw new Error("createApiClient: api client insert returned no row");
+    return { id: client.id, clientId, secret, name: input.name, role: input.role, userId: user.id };
+}
+/** Lists clients for management; the secret hash is never part of the projection. */
+export async function listApiClients(db) {
+    return db
+        .select({
+        id: apiClients.id,
+        clientId: apiClients.clientId,
+        name: apiClients.name,
+        role: apiClients.role,
+        createdAt: apiClients.createdAt,
+        revokedAt: apiClients.revokedAt,
+        lastUsedAt: apiClients.lastUsedAt,
+        userId: apiClients.userId,
+    })
+        .from(apiClients);
+}
+/**
+ * Revokes a client and every token issued to it. Returns false for an unknown id; revoking
+ * twice is a no-op that keeps the first revocation timestamp (it is an audit fact).
+ */
+export async function revokeApiClient(db, id) {
+    const found = await db
+        .select({ id: apiClients.id })
+        .from(apiClients)
+        .where(eq(apiClients.id, id))
+        .limit(1);
+    if (found.length === 0)
+        return false;
+    const now = new Date();
+    await db
+        .update(apiClients)
+        .set({ revokedAt: now })
+        .where(and(eq(apiClients.id, id), isNull(apiClients.revokedAt)));
+    await db
+        .update(apiTokens)
+        .set({ revokedAt: now })
+        .where(and(eq(apiTokens.clientId, id), isNull(apiTokens.revokedAt)));
+    return true;
+}
+/**
+ * Exchanges a client id + secret for a bearer token. Returns null for an unknown client, a
+ * wrong secret or a revoked client: the caller cannot tell which one failed.
+ */
+export async function issueApiToken(db, input) {
+    const clients = await db
+        .select({
+        id: apiClients.id,
+        userId: apiClients.userId,
+        secretHash: apiClients.secretHash,
+        revokedAt: apiClients.revokedAt,
+    })
+        .from(apiClients)
+        .where(eq(apiClients.clientId, input.clientId))
+        .limit(1);
+    const client = clients[0];
+    if (client === undefined)
+        return null;
+    if (client.revokedAt !== null)
+        return null;
+    const presentedHash = await sha256Hex(input.clientSecret);
+    if (!hashesEqual(presentedHash, client.secretHash))
+        return null;
+    const accessToken = `${ACCESS_TOKEN_PREFIX}${randomToken(ACCESS_TOKEN_BYTES)}`;
+    const expiresAt = new Date(Date.now() + input.ttlMs);
+    await db.insert(apiTokens).values({
+        tokenHash: await sha256Hex(accessToken),
+        clientId: client.id,
+        userId: client.userId,
+        expiresAt,
+    });
+    await db.update(apiClients).set({ lastUsedAt: new Date() }).where(eq(apiClients.id, client.id));
+    return { accessToken, expiresAt };
+}
+/**
+ * Validates a raw bearer token: revoked/expired tokens and tokens of a revoked client are
+ * rejected. Refreshing `last_used_at` is a conditional UPDATE, so a burst of requests does
+ * not turn into a burst of writes or race on the same row.
+ */
+export async function validateApiToken(db, rawToken) {
+    const tokenHash = await sha256Hex(rawToken);
+    const rows = await db
+        .select({
+        id: apiTokens.id,
+        userId: apiTokens.userId,
+        expiresAt: apiTokens.expiresAt,
+        revokedAt: apiTokens.revokedAt,
+        role: apiClients.role,
+        clientRevokedAt: apiClients.revokedAt,
+    })
+        .from(apiTokens)
+        .innerJoin(apiClients, eq(apiTokens.clientId, apiClients.id))
+        .where(eq(apiTokens.tokenHash, tokenHash))
+        .limit(1);
+    const found = rows[0];
+    if (found === undefined)
+        return null;
+    if (found.revokedAt !== null || found.clientRevokedAt !== null)
+        return null;
+    if (found.expiresAt.getTime() <= Date.now())
+        return null;
+    const now = new Date();
+    const staleBefore = new Date(now.getTime() - LAST_USED_WRITE_WINDOW_MS);
+    await db
+        .update(apiTokens)
+        .set({ lastUsedAt: now })
+        .where(and(eq(apiTokens.id, found.id), or(isNull(apiTokens.lastUsedAt), lt(apiTokens.lastUsedAt, staleBefore))));
+    return { userId: found.userId, role: found.role, tokenHash };
+}
+/** Constant-time comparison of two hex digests (both fixed-length SHA-256 output). */
+function hashesEqual(left, right) {
+    return constantTimeEqual(new TextEncoder().encode(left), new TextEncoder().encode(right));
+}

package/dist/crypto.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Runtime-agnostic WebCrypto access. @facilis.dev/auth runs inside a browser WebContainer too,
+ * so it uses the standard `globalThis.crypto` surface and never `node:crypto`.
+ */
+export interface SubtleCryptoLike {
+    importKey(format: "raw", keyData: Uint8Array, algorithm: "PBKDF2", extractable: boolean, keyUsages: readonly string[]): Promise<unknown>;
+    deriveBits(algorithm: {
+        name: "PBKDF2";
+        hash: "SHA-256";
+        salt: Uint8Array;
+        iterations: number;
+    }, baseKey: unknown, length: number): Promise<ArrayBuffer>;
+    digest(algorithm: "SHA-256", data: Uint8Array): Promise<ArrayBuffer>;
+}
+export interface WebCryptoLike {
+    readonly subtle: SubtleCryptoLike;
+    getRandomValues<T extends Uint8Array>(array: T): T;
+}
+export declare function webcrypto(): WebCryptoLike;
+export declare function randomBytes(length: number): Uint8Array;
+export declare function encodeBase64(bytes: Uint8Array): string;
+export declare function decodeBase64(value: string): Uint8Array | null;
+/** URL-safe random token (cookie-friendly, no padding). */
+export declare function randomToken(byteLength: number): string;
+/**
+ * SHA-256 of a string as lowercase hex. WebCrypto only, so the session-hash path also runs
+ * inside the browser WebContainer; the raw value is never stored or logged.
+ */
+export declare function sha256Hex(value: string): Promise<string>;
+/** Compares secrets without leaking the index of the first mismatch. */
+export declare function constantTimeEqual(left: Uint8Array, right: Uint8Array): boolean;

package/dist/crypto.js

@@ -0,0 +1,76 @@
+/**
+ * Runtime-agnostic WebCrypto access. @facilis.dev/auth runs inside a browser WebContainer too,
+ * so it uses the standard `globalThis.crypto` surface and never `node:crypto`.
+ */
+export function webcrypto() {
+    const crypto = globalThis.crypto;
+    if (crypto === undefined)
+        throw new Error("WebCrypto is unavailable in this runtime");
+    return crypto;
+}
+export function randomBytes(length) {
+    return webcrypto().getRandomValues(new Uint8Array(length));
+}
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+export function encodeBase64(bytes) {
+    let output = "";
+    for (let index = 0; index < bytes.length; index += 3) {
+        const first = bytes[index] ?? 0;
+        const second = bytes[index + 1];
+        const third = bytes[index + 2];
+        const triple = (first << 16) | ((second ?? 0) << 8) | (third ?? 0);
+        output += BASE64_ALPHABET[(triple >> 18) & 63] ?? "";
+        output += BASE64_ALPHABET[(triple >> 12) & 63] ?? "";
+        output += second === undefined ? "=" : (BASE64_ALPHABET[(triple >> 6) & 63] ?? "");
+        output += third === undefined ? "=" : (BASE64_ALPHABET[triple & 63] ?? "");
+    }
+    return output;
+}
+export function decodeBase64(value) {
+    if (value.length % 4 !== 0)
+        return null;
+    const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
+    const bytes = [];
+    for (let index = 0; index < value.length; index += 4) {
+        const chunk = value.slice(index, index + 4);
+        const symbols = [...chunk].map((character, offset) => {
+            if (character === "=" && offset >= 4 - padding)
+                return 0;
+            return BASE64_ALPHABET.indexOf(character);
+        });
+        if (symbols.some((symbol) => symbol < 0))
+            return null;
+        const [first = 0, second = 0, third = 0, fourth = 0] = symbols;
+        const triple = (first << 18) | (second << 12) | (third << 6) | fourth;
+        bytes.push((triple >> 16) & 255, (triple >> 8) & 255, triple & 255);
+    }
+    const paddingBytes = padding === 0 ? [] : bytes.slice(-padding);
+    if (paddingBytes.some((byte) => byte !== 0))
+        return null;
+    return new Uint8Array(padding === 0 ? bytes : bytes.slice(0, -padding));
+}
+/** URL-safe random token (cookie-friendly, no padding). */
+export function randomToken(byteLength) {
+    return encodeBase64(randomBytes(byteLength))
+        .replaceAll("+", "-")
+        .replaceAll("/", "_")
+        .replaceAll("=", "");
+}
+/**
+ * SHA-256 of a string as lowercase hex. WebCrypto only, so the session-hash path also runs
+ * inside the browser WebContainer; the raw value is never stored or logged.
+ */
+export async function sha256Hex(value) {
+    const digest = await webcrypto().subtle.digest("SHA-256", new TextEncoder().encode(value));
+    return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** Compares secrets without leaking the index of the first mismatch. */
+export function constantTimeEqual(left, right) {
+    if (left.length !== right.length)
+        return false;
+    let difference = 0;
+    for (let index = 0; index < left.length; index += 1) {
+        difference |= (left[index] ?? 0) ^ (right[index] ?? 0);
+    }
+    return difference === 0;
+}

package/dist/email-verification.d.ts

@@ -0,0 +1,45 @@
+import type { PolicyScopedDatabase } from "@facilis.dev/db";
+/**
+ * Email verification for password accounts (D-156).
+ *
+ * The primitive is split from delivery on purpose: `@facilis.dev/auth` owns the single-use token and
+ * the `users.email_verified_at` transition, while the project (or the blueprint) owns how the
+ * link reaches the mailbox. Every call runs inside the caller's audited `ctx.system` elevation,
+ * because the verification route is reached before a session exists (same D-099 shape as
+ * registration).
+ *
+ * Tokens are stored as `sha256(token)`: a tenant-scoped read of the table yields no usable link,
+ * exactly like sessions (D-144) and SSO state (D-120).
+ */
+export declare const EMAIL_VERIFICATION_TABLES: readonly ["auth_email_verifications", "users"];
+export interface IssueEmailVerificationOptions {
+    /** Link lifetime (`auth.verification.tokenTtlMs`); always validated by the caller's config. */
+    readonly ttlMs: number;
+    /** Injectable clock for tests; defaults to the wall clock. */
+    readonly now?: Date;
+}
+export interface IssuedEmailVerification {
+    /** The raw token: only the delivered link carries it, never the database or the logs. */
+    readonly token: string;
+    readonly expiresAt: Date;
+}
+/**
+ * Rotates the user's outstanding link and returns the new token. A single active token per user
+ * keeps the table small and makes "the latest email wins" true: re-registering or resending
+ * invalidates the previous link.
+ */
+export declare function issueEmailVerification(db: PolicyScopedDatabase, userId: string, options: IssueEmailVerificationOptions): Promise<IssuedEmailVerification>;
+/**
+ * Consumes a verification link: marks the user verified and returns the user id, or `null` for an
+ * unknown/expired token. The row is deleted before the expiry check, so a token is single-use even
+ * when it is already stale.
+ */
+export declare function consumeEmailVerification(db: PolicyScopedDatabase, token: string, now?: Date): Promise<{
+    userId: string;
+} | null>;
+/**
+ * Marks the account verified without a link. Used by the blueprint's development fallback (no
+ * delivery channel configured in `development`/`test`, D-146) and by tests; production always
+ * goes through the token.
+ */
+export declare function markEmailVerified(db: PolicyScopedDatabase, userId: string, now?: Date): Promise<boolean>;

package/dist/email-verification.js

@@ -0,0 +1,72 @@
+import { eq } from "drizzle-orm";
+import { randomToken, sha256Hex } from "./crypto.js";
+import { authEmailVerifications, users } from "./tables.js";
+/**
+ * Email verification for password accounts (D-156).
+ *
+ * The primitive is split from delivery on purpose: `@facilis.dev/auth` owns the single-use token and
+ * the `users.email_verified_at` transition, while the project (or the blueprint) owns how the
+ * link reaches the mailbox. Every call runs inside the caller's audited `ctx.system` elevation,
+ * because the verification route is reached before a session exists (same D-099 shape as
+ * registration).
+ *
+ * Tokens are stored as `sha256(token)`: a tenant-scoped read of the table yields no usable link,
+ * exactly like sessions (D-144) and SSO state (D-120).
+ */
+export const EMAIL_VERIFICATION_TABLES = ["auth_email_verifications", "users"];
+/**
+ * Rotates the user's outstanding link and returns the new token. A single active token per user
+ * keeps the table small and makes "the latest email wins" true: re-registering or resending
+ * invalidates the previous link.
+ */
+export async function issueEmailVerification(db, userId, options) {
+    const now = options.now ?? new Date();
+    const expiresAt = new Date(now.getTime() + options.ttlMs);
+    const token = randomToken(32);
+    await db.delete(authEmailVerifications).where(eq(authEmailVerifications.userId, userId));
+    await db.insert(authEmailVerifications).values({
+        id: await sha256Hex(token),
+        userId,
+        createdAt: now,
+        expiresAt,
+    });
+    return { token, expiresAt };
+}
+/**
+ * Consumes a verification link: marks the user verified and returns the user id, or `null` for an
+ * unknown/expired token. The row is deleted before the expiry check, so a token is single-use even
+ * when it is already stale.
+ */
+export async function consumeEmailVerification(db, token, now = new Date()) {
+    const id = await sha256Hex(token);
+    const rows = await db
+        .select({ userId: authEmailVerifications.userId, expiresAt: authEmailVerifications.expiresAt })
+        .from(authEmailVerifications)
+        .where(eq(authEmailVerifications.id, id))
+        .limit(1);
+    const row = rows[0];
+    if (row === undefined)
+        return null;
+    await db.delete(authEmailVerifications).where(eq(authEmailVerifications.id, id));
+    if (row.expiresAt.getTime() <= now.getTime())
+        return null;
+    const updated = await db
+        .update(users)
+        .set({ emailVerifiedAt: now })
+        .where(eq(users.id, row.userId))
+        .returning({ id: users.id });
+    return updated[0] === undefined ? null : { userId: updated[0].id };
+}
+/**
+ * Marks the account verified without a link. Used by the blueprint's development fallback (no
+ * delivery channel configured in `development`/`test`, D-146) and by tests; production always
+ * goes through the token.
+ */
+export async function markEmailVerified(db, userId, now = new Date()) {
+    const updated = await db
+        .update(users)
+        .set({ emailVerifiedAt: now })
+        .where(eq(users.id, userId))
+        .returning({ id: users.id });
+    return updated[0] !== undefined;
+}

package/dist/email.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Canonical email form (D-150). Registration, login, SSO linking and the bootstrap comparison
+ * all go through this function: the stored value, the unique `lower(email)` index and every
+ * lookup then agree on one identity, so a case variant can never create a second account or
+ * be mistaken for another one during the initial-admin promotion.
+ */
+export declare function normalizeEmail(email: string): string;

package/dist/email.js

@@ -0,0 +1,9 @@
+/**
+ * Canonical email form (D-150). Registration, login, SSO linking and the bootstrap comparison
+ * all go through this function: the stored value, the unique `lower(email)` index and every
+ * lookup then agree on one identity, so a case variant can never create a second account or
+ * be mistaken for another one during the initial-admin promotion.
+ */
+export function normalizeEmail(email) {
+    return email.trim().toLowerCase();
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @facilis.dev/auth — auth tables, RBAC expansion, password hashing, sessions and seeding.
+ */
+export { apiClients, apiTokens, authEmailVerifications, rolePermissions, roles, sessions, userRoles, users, type ApiClientRow, type ApiTokenRow, type AuthUser, type EmailVerificationRow, type NewEmailVerificationRow, type NewUserRow, type RolePermissionRow, type RoleRow, type SessionRow, type UserRoleRow, type UserRow, } from "./tables.js";
+export { createApiClient, issueApiToken, listApiClients, revokeApiClient, validateApiToken, type ApiClientSummary, type CreateApiClientInput, type CreatedApiClient, type IssuedApiToken, type IssueApiTokenInput, type ValidatedApiToken, } from "./api-clients.js";
+export { normalizeEmail } from "./email.js";
+export { expandRoles, hasPermission, type AuthConfig, type AuthContext } from "./roles.js";
+export { consumeEmailVerification, EMAIL_VERIFICATION_TABLES, issueEmailVerification, markEmailVerified, type IssuedEmailVerification, type IssueEmailVerificationOptions, } from "./email-verification.js";
+export { hashPassword, verifyPassword } from "./password.js";
+export { createSession, destroySession, SESSION_COOKIE_NAME, sessionMiddleware, validateSession, type CreateSessionOptions, type SessionEvent, type SessionEventContext, type SessionMiddlewareDeps, type ValidatedSession, } from "./session.js";
+export { registerInitialAdmin, seedFromConfig, seedStatements, type SeedEntry } from "./seed.js";
+export * from "./sso/index.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * @facilis.dev/auth — auth tables, RBAC expansion, password hashing, sessions and seeding.
+ */
+export { apiClients, apiTokens, authEmailVerifications, rolePermissions, roles, sessions, userRoles, users, } from "./tables.js";
+export { createApiClient, issueApiToken, listApiClients, revokeApiClient, validateApiToken, } from "./api-clients.js";
+export { normalizeEmail } from "./email.js";
+export { expandRoles, hasPermission } from "./roles.js";
+export { consumeEmailVerification, EMAIL_VERIFICATION_TABLES, issueEmailVerification, markEmailVerified, } from "./email-verification.js";
+export { hashPassword, verifyPassword } from "./password.js";
+export { createSession, destroySession, SESSION_COOKIE_NAME, sessionMiddleware, validateSession, } from "./session.js";
+export { registerInitialAdmin, seedFromConfig, seedStatements } from "./seed.js";
+export * from "./sso/index.js";

package/dist/password.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Hashes a password with PBKDF2-SHA256 (WebCrypto). Encoding is versioned and
+ * self-describing: `pbkdf2-sha256$<iterations>$<saltB64>$<hashB64>`.
+ */
+export declare function hashPassword(password: string): Promise<string>;
+/** Constant-time verification; malformed or unsupported hashes return false, never throw. */
+export declare function verifyPassword(hash: string, password: string): Promise<boolean>;

package/dist/password.js

@@ -0,0 +1,54 @@
+import { constantTimeEqual, decodeBase64, encodeBase64, randomBytes, webcrypto } from "./crypto.js";
+const ALGORITHM = "pbkdf2-sha256";
+const DEFAULT_ITERATIONS = 600_000;
+const MAX_ITERATIONS = 1_000_000;
+const SALT_BYTES = 16;
+const KEY_BITS = 256;
+const KEY_BYTES = KEY_BITS / 8;
+/**
+ * Hashes a password with PBKDF2-SHA256 (WebCrypto). Encoding is versioned and
+ * self-describing: `pbkdf2-sha256$<iterations>$<saltB64>$<hashB64>`.
+ */
+export async function hashPassword(password) {
+    const salt = randomBytes(SALT_BYTES);
+    const hash = await deriveKey(password, salt, DEFAULT_ITERATIONS);
+    return [ALGORITHM, String(DEFAULT_ITERATIONS), encodeBase64(salt), encodeBase64(hash)].join("$");
+}
+/** Constant-time verification; malformed or unsupported hashes return false, never throw. */
+export async function verifyPassword(hash, password) {
+    const parsed = parsePasswordHash(hash);
+    if (parsed === null)
+        return false;
+    const candidate = await deriveKey(password, parsed.salt, parsed.iterations);
+    return constantTimeEqual(candidate, parsed.hash);
+}
+function parsePasswordHash(value) {
+    const parts = value.split("$");
+    if (parts.length !== 4)
+        return null;
+    const [algorithm, iterationsText, saltText, hashText] = parts;
+    if (algorithm !== ALGORITHM ||
+        iterationsText === undefined ||
+        saltText === undefined ||
+        hashText === undefined ||
+        !/^[1-9][0-9]*$/.test(iterationsText)) {
+        return null;
+    }
+    const iterations = Number(iterationsText);
+    if (iterations > MAX_ITERATIONS)
+        return null;
+    const salt = decodeBase64(saltText);
+    const hash = decodeBase64(hashText);
+    if (salt === null || hash === null || salt.length !== SALT_BYTES || hash.length !== KEY_BYTES) {
+        return null;
+    }
+    return { iterations, salt, hash };
+}
+async function deriveKey(password, salt, iterations) {
+    const { subtle } = webcrypto();
+    const key = await subtle.importKey("raw", new TextEncoder().encode(password), "PBKDF2", false, [
+        "deriveBits",
+    ]);
+    const bits = await subtle.deriveBits({ name: "PBKDF2", hash: "SHA-256", salt, iterations }, key, KEY_BITS);
+    return new Uint8Array(bits);
+}