@synoikia/core 0.1.0

package/dist/auth/tokens.js

@@ -0,0 +1,40 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+/** Random opaque tokens (stored hashed) and short-lived HMAC-signed payloads for multi-step flows. */
+export function randomToken(bytes = 32) {
+    return randomBytes(bytes).toString('base64url');
+}
+export function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+/** Signs a small JSON payload with an expiry. Used for the TOTP step, OIDC state and consent forms. */
+export function signPayload(key, payload, ttlMs, nowMs = Date.now()) {
+    const body = Buffer.from(JSON.stringify({ ...payload, exp: nowMs + ttlMs })).toString('base64url');
+    const mac = createHmac('sha256', key).update(body).digest('base64url');
+    return `${body}.${mac}`;
+}
+export function verifyPayload(key, token, nowMs = Date.now()) {
+    if (!token)
+        return null;
+    const [body, mac] = token.split('.');
+    if (!body || !mac)
+        return null;
+    const expected = Buffer.from(createHmac('sha256', key).update(body).digest('base64url'));
+    const given = Buffer.from(mac);
+    if (expected.length !== given.length || !timingSafeEqual(expected, given))
+        return null;
+    try {
+        const payload = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+        if (typeof payload.exp !== 'number' || payload.exp < nowMs)
+            return null;
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}
+export function safeEqual(a, b) {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    return ab.length === bb.length && timingSafeEqual(ab, bb);
+}
+//# sourceMappingURL=tokens.js.map

package/dist/auth/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/auth/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnF,sGAAsG;AAEtG,MAAM,UAAU,WAAW,CAAC,KAAK,GAAG,EAAE;IACpC,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,KAAa;IAClC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,OAAgC,EAAE,KAAa,EAAE,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE;IAC1G,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,OAAO,EAAE,GAAG,EAAE,KAAK,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IACnG,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IACvE,OAAO,GAAG,IAAI,IAAI,GAAG,EAAE,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,GAAW,EACX,KAAyB,EACzB,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE;IAElB,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,CAAC,IAAI,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC;IACzF,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,QAAQ,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,IAAI,CAAC,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvF,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAyB,CAAC;QACpG,IAAI,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,IAAI,OAAO,CAAC,GAAG,GAAG,KAAK;YAAE,OAAO,IAAI,CAAC;QACxE,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,CAAS,EAAE,CAAS;IAC5C,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,OAAO,EAAE,CAAC,MAAM,KAAK,EAAE,CAAC,MAAM,IAAI,eAAe,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AAC5D,CAAC"}

package/dist/auth/totp.d.ts

@@ -0,0 +1,14 @@
+export declare function base32Encode(buf: Buffer): string;
+export declare function base32Decode(input: string): Buffer;
+export declare function generateTotpSecret(): string;
+export declare function totpAt(secret: string, step: number): string;
+export declare const currentStep: (nowMs?: number) => number;
+/**
+ * Checks a code against the current step ±1 (clock drift) and returns the matched step, or null.
+ * Callers must reject steps ≤ the last accepted one to prevent replay.
+ */
+export declare function verifyTotp(secret: string, code: string, opts?: {
+    nowMs?: number;
+    lastStep?: number | null;
+}): number | null;
+export declare function otpauthUri(secret: string, account: string, issuer?: string): string;

package/dist/auth/totp.js

@@ -0,0 +1,81 @@
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+/** RFC 6238 TOTP (SHA-1, 6 digits, 30 s) — the parameters every authenticator app supports. */
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+const STEP_SECONDS = 30;
+const DIGITS = 6;
+export function base32Encode(buf) {
+    let bits = 0;
+    let value = 0;
+    let out = '';
+    for (const byte of buf) {
+        value = (value << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            out += ALPHABET[(value >>> (bits - 5)) & 31];
+            bits -= 5;
+        }
+    }
+    if (bits > 0)
+        out += ALPHABET[(value << (5 - bits)) & 31];
+    return out;
+}
+export function base32Decode(input) {
+    const clean = input.toUpperCase().replace(/[\s=-]/g, '');
+    let bits = 0;
+    let value = 0;
+    const out = [];
+    for (const ch of clean) {
+        const idx = ALPHABET.indexOf(ch);
+        if (idx === -1)
+            throw new Error('Invalid base32');
+        value = (value << 5) | idx;
+        bits += 5;
+        if (bits >= 8) {
+            out.push((value >>> (bits - 8)) & 0xff);
+            bits -= 8;
+        }
+    }
+    return Buffer.from(out);
+}
+export function generateTotpSecret() {
+    return base32Encode(randomBytes(20));
+}
+export function totpAt(secret, step) {
+    const counter = Buffer.alloc(8);
+    counter.writeBigUInt64BE(BigInt(step));
+    const mac = createHmac('sha1', base32Decode(secret)).update(counter).digest();
+    const offset = mac[mac.length - 1] & 0x0f;
+    const code = (mac.readUInt32BE(offset) & 0x7fffffff) % 10 ** DIGITS;
+    return code.toString().padStart(DIGITS, '0');
+}
+export const currentStep = (nowMs = Date.now()) => Math.floor(nowMs / 1000 / STEP_SECONDS);
+/**
+ * Checks a code against the current step ±1 (clock drift) and returns the matched step, or null.
+ * Callers must reject steps ≤ the last accepted one to prevent replay.
+ */
+export function verifyTotp(secret, code, opts = {}) {
+    const normalized = code.replace(/\s/g, '');
+    if (!/^\d{6}$/.test(normalized))
+        return null;
+    const now = currentStep(opts.nowMs);
+    for (const step of [now - 1, now, now + 1]) {
+        if (opts.lastStep != null && step <= opts.lastStep)
+            continue;
+        const expected = Buffer.from(totpAt(secret, step));
+        if (timingSafeEqual(expected, Buffer.from(normalized)))
+            return step;
+    }
+    return null;
+}
+export function otpauthUri(secret, account, issuer = 'Synoikia') {
+    const label = encodeURIComponent(`${issuer}:${account}`);
+    const params = new URLSearchParams({
+        secret,
+        issuer,
+        algorithm: 'SHA1',
+        digits: String(DIGITS),
+        period: String(STEP_SECONDS),
+    });
+    return `otpauth://totp/${label}?${params.toString()}`;
+}
+//# sourceMappingURL=totp.js.map

package/dist/auth/totp.js.map

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

package/dist/auth/users.d.ts

@@ -0,0 +1,70 @@
+import type { SecretBox } from '../crypto/index.js';
+import type { Db } from '../db/index.js';
+import { users } from '../db/schema.js';
+export type UserRow = typeof users.$inferSelect;
+export interface PublicUser {
+    id: string;
+    username: string;
+    totpEnabled: boolean;
+    oidcLinked: boolean;
+    hasPassword: boolean;
+    disabled: boolean;
+    createdAt: Date;
+    lastLoginAt: Date | null;
+}
+export declare const toPublicUser: (u: UserRow) => PublicUser;
+export declare function checkPasswordPolicy(password: string): void;
+export declare class UserService {
+    private readonly db;
+    private readonly box;
+    constructor(db: Db, box: SecretBox);
+    count(): number;
+    list(): PublicUser[];
+    get(id: string): UserRow;
+    byUsername(username: string): UserRow | undefined;
+    byOidc(issuer: string, subject: string): UserRow | undefined;
+    create(input: {
+        username: string;
+        password?: string;
+    }, actor?: {
+        userId?: string;
+    }, opts?: {
+        onlyIfFirst?: boolean;
+    }): Promise<PublicUser>;
+    /** First-run setup: only while no users exist (design §6.1). */
+    setupFirstUser(username: string, password: string): Promise<PublicUser>;
+    /** `ADMIN_BOOTSTRAP_*`: create the first user on boot if none exist; ignored afterwards. */
+    bootstrap(username?: string, password?: string): Promise<'created' | 'ignored' | 'not_configured'>;
+    verifyPassword(username: string, password: string): Promise<UserRow | null>;
+    setPassword(userId: string, password: string, opts?: {
+        currentPassword?: string;
+        actorId?: string;
+    }): Promise<void>;
+    setDisabled(userId: string, disabled: boolean, actor?: {
+        userId?: string;
+    }): void;
+    markLogin(userId: string): void;
+    private totpSecret;
+    /** Starts (or restarts) enrollment. TOTP stays off until `confirmTotp` succeeds. */
+    beginTotp(userId: string): {
+        secret: string;
+        uri: string;
+    };
+    /** Confirms enrollment with a first code; returns the recovery codes, which are shown only once. */
+    confirmTotp(userId: string, code: string): string[];
+    resetTotp(userId: string, actor?: {
+        userId?: string;
+    }): void;
+    /**
+     * A TOTP code only (replay-protected), for checks that must not accept, or use up, a recovery code
+     * (the approval page).
+     */
+    verifyTotpCode(userId: string, code: string): boolean;
+    /** Second factor: a TOTP code (replay-protected) or a single-use recovery code. */
+    verifySecondFactor(userId: string, code: string): 'totp' | 'recovery' | null;
+    linkOidc(userId: string, issuer: string, subject: string): void;
+    unlinkOidc(userId: string, actor?: {
+        userId?: string;
+    }): void;
+    hasOidcLinkedUser(except?: string): boolean;
+}

package/dist/auth/users.js

@@ -0,0 +1,296 @@
+import { randomUUID } from 'node:crypto';
+import { hash, verify } from '@node-rs/argon2';
+import { and, asc, count, eq } from 'drizzle-orm';
+import { writeAudit } from '../audit.js';
+import { aad } from '../crypto/index.js';
+import { users } from '../db/schema.js';
+import { ConflictError, NotFoundError, ValidationError } from '../errors.js';
+import { randomToken, sha256 } from './tokens.js';
+import { generateTotpSecret, otpauthUri, verifyTotp } from './totp.js';
+/**
+ * Portal accounts (design §6.1): local users with argon2id passwords, optional TOTP with recovery
+ * codes, optional OIDC link. No roles — every user is an admin.
+ */
+// argon2id, m = 64 MiB, t = 3, p = 1 (design §6.1). @node-rs/argon2 defaults to argon2id.
+const ARGON = { memoryCost: 65536, timeCost: 3, parallelism: 1 };
+const USERNAME = /^[a-zA-Z0-9._@-]{2,64}$/;
+const RECOVERY_CODES = 10;
+export const toPublicUser = (u) => ({
+    id: u.id,
+    username: u.username,
+    totpEnabled: u.totpEnabled,
+    oidcLinked: !!u.oidcSubject,
+    hasPassword: !!u.passwordHash,
+    disabled: u.disabled,
+    createdAt: u.createdAt,
+    lastLoginAt: u.lastLoginAt,
+});
+export function checkPasswordPolicy(password) {
+    if (typeof password !== 'string' || password.length < 12) {
+        throw new ValidationError('weak_password', 'Passwords must be at least 12 characters');
+    }
+    if (password.length > 1024)
+        throw new ValidationError('weak_password', 'Password is too long');
+}
+// Verified when the username doesn't exist, so response timing doesn't reveal which usernames exist.
+let dummyHash;
+export class UserService {
+    db;
+    box;
+    constructor(db, box) {
+        this.db = db;
+        this.box = box;
+    }
+    count() {
+        return this.db.select({ n: count() }).from(users).get()?.n ?? 0;
+    }
+    list() {
+        return this.db.select().from(users).orderBy(asc(users.username)).all().map(toPublicUser);
+    }
+    get(id) {
+        const u = this.db.select().from(users).where(eq(users.id, id)).get();
+        if (!u)
+            throw new NotFoundError('user_not_found', 'No such user');
+        return u;
+    }
+    byUsername(username) {
+        return this.db.select().from(users).where(eq(users.username, username)).get();
+    }
+    byOidc(issuer, subject) {
+        return this.db
+            .select()
+            .from(users)
+            .where(and(eq(users.oidcIssuer, issuer), eq(users.oidcSubject, subject)))
+            .get();
+    }
+    async create(input, actor = {}, opts = {}) {
+        const username = input.username.trim();
+        if (!USERNAME.test(username)) {
+            throw new ValidationError('invalid_username', 'Usernames are 2–64 letters, digits, dots, dashes, underscores or @');
+        }
+        if (this.byUsername(username))
+            throw new ConflictError('username_taken', 'That username is taken');
+        if (input.password !== undefined)
+            checkPasswordPolicy(input.password);
+        const row = {
+            id: randomUUID(),
+            username,
+            passwordHash: input.password ? await hash(input.password, ARGON) : null,
+            createdAt: new Date(),
+        };
+        this.db.transaction((tx) => {
+            // Re-checked after the (slow) hash, in the same transaction as the insert: of two concurrent
+            // first-run setups only one creates a user.
+            if (opts.onlyIfFirst && (tx.select({ n: count() }).from(users).get()?.n ?? 0) > 0)
+                throw new ConflictError('setup_done', 'Setup has already been completed');
+            if (tx.select({ id: users.id }).from(users).where(eq(users.username, username)).get())
+                throw new ConflictError('username_taken', 'That username is taken');
+            tx.insert(users).values(row).run();
+            writeAudit(tx, {
+                kind: 'auth',
+                decision: 'user_created',
+                actorKind: actor.userId ? 'user' : 'system',
+                actorId: actor.userId,
+                detail: { username },
+            });
+        });
+        return toPublicUser(this.get(row.id));
+    }
+    /** First-run setup: only while no users exist (design §6.1). */
+    async setupFirstUser(username, password) {
+        if (this.count() > 0)
+            throw new ConflictError('setup_done', 'Setup has already been completed');
+        return this.create({ username, password }, {}, { onlyIfFirst: true });
+    }
+    /** `ADMIN_BOOTSTRAP_*`: create the first user on boot if none exist; ignored afterwards. */
+    async bootstrap(username, password) {
+        if (!username || !password)
+            return 'not_configured';
+        if (this.count() > 0)
+            return 'ignored';
+        await this.create({ username, password }, {}, { onlyIfFirst: true });
+        return 'created';
+    }
+    async verifyPassword(username, password) {
+        const user = this.byUsername(username);
+        if (!user?.passwordHash || user.disabled) {
+            dummyHash ??= hash(randomToken(), ARGON);
+            await verify(await dummyHash, password).catch(() => false);
+            return null;
+        }
+        return (await verify(user.passwordHash, password).catch(() => false)) ? user : null;
+    }
+    async setPassword(userId, password, opts = {}) {
+        const user = this.get(userId);
+        if (opts.currentPassword !== undefined && user.passwordHash) {
+            if (!(await verify(user.passwordHash, opts.currentPassword).catch(() => false))) {
+                throw new ValidationError('wrong_password', 'Current password is incorrect');
+            }
+        }
+        checkPasswordPolicy(password);
+        const passwordHash = await hash(password, ARGON);
+        this.db.transaction((tx) => {
+            tx.update(users).set({ passwordHash }).where(eq(users.id, userId)).run();
+            writeAudit(tx, {
+                kind: 'auth',
+                decision: 'password_changed',
+                actorKind: 'user',
+                actorId: opts.actorId ?? userId,
+                detail: { username: user.username },
+            });
+        });
+    }
+    setDisabled(userId, disabled, actor = {}) {
+        const user = this.get(userId);
+        if (disabled) {
+            const active = this.db.select().from(users).where(eq(users.disabled, false)).all();
+            if (active.length === 1 && active[0].id === userId) {
+                throw new ConflictError('last_user', 'You cannot disable the last active user');
+            }
+        }
+        this.db.transaction((tx) => {
+            tx.update(users).set({ disabled }).where(eq(users.id, userId)).run();
+            writeAudit(tx, {
+                kind: 'auth',
+                decision: disabled ? 'user_disabled' : 'user_enabled',
+                actorKind: 'user',
+                actorId: actor.userId,
+                detail: { username: user.username },
+            });
+        });
+    }
+    markLogin(userId) {
+        this.db.update(users).set({ lastLoginAt: new Date() }).where(eq(users.id, userId)).run();
+    }
+    // ── TOTP ─────────────────────────────────────────────────────────────────────────────────────────
+    totpSecret(user) {
+        if (!user.totpSecretEnc)
+            return null;
+        return this.box.decrypt(user.totpSecretEnc, aad('users', 'totp_secret_enc', user.id)).toString('utf8');
+    }
+    /** Starts (or restarts) enrollment. TOTP stays off until `confirmTotp` succeeds. */
+    beginTotp(userId) {
+        const user = this.get(userId);
+        if (user.totpEnabled)
+            throw new ConflictError('totp_enabled', 'TOTP is already enabled; reset it first');
+        const secret = generateTotpSecret();
+        this.db
+            .update(users)
+            .set({ totpSecretEnc: this.box.encrypt(secret, aad('users', 'totp_secret_enc', userId)), totpLastStep: null })
+            .where(eq(users.id, userId))
+            .run();
+        return { secret, uri: otpauthUri(secret, user.username) };
+    }
+    /** Confirms enrollment with a first code; returns the recovery codes, which are shown only once. */
+    confirmTotp(userId, code) {
+        const user = this.get(userId);
+        const secret = this.totpSecret(user);
+        if (!secret || user.totpEnabled)
+            throw new ConflictError('totp_not_pending', 'Start TOTP enrollment first');
+        const step = verifyTotp(secret, code);
+        if (step === null)
+            throw new ValidationError('invalid_code', 'That code is not valid');
+        const codes = Array.from({ length: RECOVERY_CODES }, () => randomToken(8).replace(/[-_]/g, '').slice(0, 10).toLowerCase());
+        this.db.transaction((tx) => {
+            tx.update(users)
+                .set({ totpEnabled: true, totpLastStep: step, recoveryCodesHash: codes.map(sha256) })
+                .where(eq(users.id, userId))
+                .run();
+            writeAudit(tx, {
+                kind: 'auth',
+                decision: 'totp_enabled',
+                actorKind: 'user',
+                actorId: userId,
+                detail: { username: user.username },
+            });
+        });
+        return codes;
+    }
+    resetTotp(userId, actor = {}) {
+        const user = this.get(userId);
+        this.db.transaction((tx) => {
+            tx.update(users)
+                .set({ totpEnabled: false, totpSecretEnc: null, totpLastStep: null, recoveryCodesHash: null })
+                .where(eq(users.id, userId))
+                .run();
+            writeAudit(tx, {
+                kind: 'auth',
+                decision: 'totp_reset',
+                actorKind: 'user',
+                actorId: actor.userId ?? userId,
+                detail: { username: user.username },
+            });
+        });
+    }
+    /**
+     * A TOTP code only (replay-protected), for checks that must not accept, or use up, a recovery code
+     * (the approval page).
+     */
+    verifyTotpCode(userId, code) {
+        const user = this.get(userId);
+        const secret = this.totpSecret(user);
+        if (!user.totpEnabled || !secret)
+            return false;
+        const step = verifyTotp(secret, code, { lastStep: user.totpLastStep });
+        if (step === null)
+            return false;
+        this.db.update(users).set({ totpLastStep: step }).where(eq(users.id, userId)).run();
+        return true;
+    }
+    /** Second factor: a TOTP code (replay-protected) or a single-use recovery code. */
+    verifySecondFactor(userId, code) {
+        const user = this.get(userId);
+        if (!user.totpEnabled || !this.totpSecret(user))
+            return null;
+        if (this.verifyTotpCode(userId, code))
+            return 'totp';
+        const hashed = sha256(code.trim().toLowerCase());
+        const remaining = user.recoveryCodesHash ?? [];
+        if (remaining.includes(hashed)) {
+            this.db
+                .update(users)
+                .set({ recoveryCodesHash: remaining.filter((h) => h !== hashed) })
+                .where(eq(users.id, userId))
+                .run();
+            writeAudit(this.db, {
+                kind: 'auth',
+                decision: 'recovery_code_used',
+                actorKind: 'user',
+                actorId: userId,
+                detail: { remaining: remaining.length - 1 },
+            });
+            return 'recovery';
+        }
+        return null;
+    }
+    // ── OIDC links ───────────────────────────────────────────────────────────────────────────────────
+    linkOidc(userId, issuer, subject) {
+        const existing = this.byOidc(issuer, subject);
+        if (existing && existing.id !== userId)
+            throw new ConflictError('oidc_taken', 'That identity is linked to another user');
+        this.db.transaction((tx) => {
+            tx.update(users).set({ oidcIssuer: issuer, oidcSubject: subject }).where(eq(users.id, userId)).run();
+            writeAudit(tx, {
+                kind: 'auth',
+                decision: 'oidc_linked',
+                actorKind: 'user',
+                actorId: userId,
+                detail: { issuer, subject },
+            });
+        });
+    }
+    unlinkOidc(userId, actor = {}) {
+        this.db.transaction((tx) => {
+            tx.update(users).set({ oidcIssuer: null, oidcSubject: null }).where(eq(users.id, userId)).run();
+            writeAudit(tx, { kind: 'auth', decision: 'oidc_unlinked', actorKind: 'user', actorId: actor.userId ?? userId });
+        });
+    }
+    hasOidcLinkedUser(except) {
+        return this.db
+            .select()
+            .from(users)
+            .all()
+            .some((u) => !!u.oidcSubject && !u.disabled && u.id !== except);
+    }
+}
+//# sourceMappingURL=users.js.map

package/dist/auth/users.js.map

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

package/dist/catalog/groups.d.ts

@@ -0,0 +1,102 @@
+import type { Db, DbLike } from '../db/index.js';
+import { operations } from '../db/schema.js';
+import type { AccessDecision, AccessLevel, AccessPrincipal } from '../gate/access.js';
+type OperationRow = typeof operations.$inferSelect;
+export interface Actor {
+    userId?: string;
+}
+export declare const accessInput: (op: OperationRow) => {
+    classification: "read" | "write";
+    locked: boolean;
+    levelOverride: "none" | "read" | "ask" | "write" | null;
+    writeAcknowledged: boolean;
+};
+export interface GroupSummary {
+    key: string;
+    label: string;
+    level: AccessLevel;
+    stale: boolean;
+    counts: {
+        read: number;
+        write: number;
+        locked: number;
+        pendingReview: number;
+        overridden: number;
+    };
+}
+export declare function listGroups(db: DbLike, instanceId: string): GroupSummary[];
+/** Access decision for one operation key; unknown or stale operations are unreachable. */
+export declare function resolveAccess(db: DbLike, instanceId: string, key: string, principal?: AccessPrincipal): AccessDecision | {
+    reachable: false;
+    reason: 'unknown_operation';
+};
+/**
+ * Sets one group's level; operations with their own level keep it. Raising to `write` must carry
+ * `acknowledge` = exactly the writes that will then run without asking (the list the admin was
+ * shown); if a sync changed that list in between, this fails with 409 and the fresh list.
+ */
+export declare function setGroupLevel(db: Db, instanceId: string, key: string, level: string, opts?: {
+    acknowledge?: string[];
+    actor?: Actor;
+    now?: Date;
+}): GroupSummary;
+export interface BulkPreview {
+    level: AccessLevel;
+    /** `exposes`: writes that will run without asking at `write` (only listed for a `write` preview). */
+    groups: {
+        key: string;
+        label: string;
+        from: AccessLevel;
+        exposes: {
+            id: string;
+            key: string;
+        }[];
+    }[];
+    /** Pass back unchanged as `acknowledge` when applying a bulk `write`. */
+    acknowledge: string[];
+}
+export declare function previewBulkLevel(db: DbLike, instanceId: string, level: string): BulkPreview;
+/**
+ * Sets every group of an instance to one level (operations with their own level keep it).
+ * `none`/`read`/`ask` apply directly. `write` requires `confirm` = the instance slug and
+ * `acknowledge` = the current preview's list. Locked operations never auto-run.
+ */
+export declare function applyBulkLevel(db: Db, instanceId: string, level: string, opts?: {
+    confirm?: string;
+    acknowledge?: string[];
+    actor?: Actor;
+    now?: Date;
+}): BulkPreview['groups'];
+export declare function renameGroup(db: Db, instanceId: string, key: string, label: string, opts?: {
+    actor?: Actor;
+}): void;
+/**
+ * Merges groups into `into` (created if new). Stored as aliases so future syncs keep the grouping.
+ * The merged group takes the lowest level involved, so merging never widens access.
+ */
+export declare function mergeGroups(db: Db, instanceId: string, input: {
+    from: string[];
+    into: string;
+    label?: string;
+}, opts?: {
+    actor?: Actor;
+    now?: Date;
+}): GroupSummary;
+export interface OperationPatch {
+    /** The operation's own level; `null` makes it follow its group again. */
+    level?: AccessLevel | null;
+    acknowledged?: boolean;
+    classification?: 'read' | 'write';
+    /** Require a best-practice key (guides) for this operation; turning it off is remembered across syncs. */
+    attestationRequired?: boolean;
+}
+/**
+ * Per-operation level, acknowledgement and classification override. Locked operations can't be set
+ * to `write` and can't change classification (409). Setting a write to `write`, or overriding an
+ * operation's classification to write, acknowledges it.
+ */
+export declare function updateOperation(db: Db, instanceId: string, opId: string, patch: OperationPatch, opts?: {
+    actor?: Actor;
+    now?: Date;
+}): void;
+export {};