@kelpie/server 0.1.0

package/dist/lib/pagination.d.ts

@@ -0,0 +1,104 @@
+import type { Column, SQL } from 'drizzle-orm';
+/**
+ * Cursor pagination from `api.md`: `?limit=` and `?cursor=`, an opaque cursor,
+ * and `{ data, next_cursor }` on the wire.
+ *
+ * The cursor is a keyset rather than an offset. It carries the sort value and id
+ * of the last row on the page, so a page boundary stays put when rows are
+ * inserted or deleted underneath a client. Offsets skip and repeat rows when that
+ * happens, which for a CRM that agents write to is not a rare case.
+ *
+ * A cursor is bound to the sort it was issued under. Reusing one against a
+ * different `?sort=` is a client bug, and it is reported as one rather than
+ * silently paging through a different order.
+ */
+export declare const DEFAULT_PAGE_SIZE = 50;
+export declare const MAX_PAGE_SIZE = 200;
+/** A field a list may be ordered by, and how its value survives a round trip through a cursor. */
+export interface SortableField<TRecord> {
+    readonly column: Column;
+    /** Reads the cursor value out of the last row of a page. */
+    readonly valueOf: (record: TRecord) => string;
+    /** Turns that string back into something comparable against the column. */
+    readonly parse: (value: string) => Date | string | number;
+}
+/** The documented sort fields of one resource, keyed by their wire name. */
+export type SortableFields<TRecord> = Readonly<Record<string, SortableField<TRecord>>>;
+/** Where the previous page stopped. */
+export interface CursorPosition {
+    readonly value: Date | string | number;
+    readonly id: string;
+}
+export interface ListWindow<TRecord> {
+    /** How many rows the caller asked for. */
+    readonly limit: number;
+    /** What to ask the database for: one more than `limit`, to detect a next page. */
+    readonly fetchLimit: number;
+    /** The canonical sort spec, `-created_at` style. Cursors are bound to it. */
+    readonly sort: string;
+    readonly field: SortableField<TRecord>;
+    readonly descending: boolean;
+    readonly position: CursorPosition | undefined;
+}
+export interface Page<TRecord> {
+    readonly items: readonly TRecord[];
+    readonly nextCursor: string | null;
+}
+export interface ListQueryParameters {
+    readonly limit?: string | undefined;
+    readonly sort?: string | undefined;
+    readonly cursor?: string | undefined;
+}
+export declare function textSort<TRecord>(column: Column, valueOf: (record: TRecord) => string): SortableField<TRecord>;
+export declare function integerSort<TRecord>(column: Column, valueOf: (record: TRecord) => number): SortableField<TRecord>;
+export declare function timestampSort<TRecord>(column: Column, valueOf: (record: TRecord) => Date): SortableField<TRecord>;
+/**
+ * Reads `?limit=` against the `api.md` range.
+ *
+ * Exported for the endpoints that take the same parameter without being paged
+ * lists. The dashboard is the case: it caps several embedded lists at once and
+ * issues no cursor, but the ceiling a caller may ask for is the same one.
+ *
+ * @throws AppError 422 for anything but a whole number in range.
+ */
+export declare function readPageSize(raw: string | undefined): number;
+/**
+ * Reads `?limit=`, `?sort=` and `?cursor=` into a window a repository can apply.
+ *
+ * @param defaultSort The resource's own default, `-created_at` style. Naming a
+ *   field the resource does not declare is a programming error, not a request
+ *   error, so it throws rather than producing a 422.
+ * @throws AppError 422 for an out-of-range limit, an undocumented sort field, or
+ *   a cursor that is unreadable or belongs to a different sort order.
+ */
+export declare function readListWindow<TRecord>(query: ListQueryParameters, fields: SortableFields<TRecord>, defaultSort: string): ListWindow<TRecord>;
+/**
+ * The keyset predicate: everything after the cursor's row in the window's order.
+ *
+ * Values go through `sql.param` with their own column as the encoder. A bare
+ * `${value}` in a template reaches the driver unconverted, and postgres.js has no
+ * column to infer from, so a `Date` arrives where it wants a string.
+ *
+ * @returns undefined on the first page, where there is nothing to seek past.
+ */
+export declare function keysetCondition<TRecord>(window: ListWindow<TRecord>, idColumn: Column): SQL | undefined;
+/**
+ * The ordering, id included. Without the id tiebreak two rows sharing a sort
+ * value could straddle a page boundary in either order, and one of them would be
+ * lost or repeated.
+ */
+export declare function orderByWindow<TRecord>(window: ListWindow<TRecord>, idColumn: Column): SQL[];
+/**
+ * Trims the extra row a repository fetched and turns it into a next cursor.
+ *
+ * @param rows Up to `window.fetchLimit` rows, in the window's order.
+ */
+export declare function toPage<TRecord>(rows: readonly TRecord[], window: ListWindow<TRecord>, idOf: (record: TRecord) => string): Page<TRecord>;
+/**
+ * Re-shapes the items of a page, leaving the cursor alone.
+ *
+ * A service pages over stored rows and answers with views, and the cursor is
+ * built from the row it came from, not from what the caller is handed back.
+ */
+export declare function mapPage<TFrom, TTo>(page: Page<TFrom>, render: (item: TFrom) => TTo): Page<TTo>;
+//# sourceMappingURL=pagination.d.ts.map

package/dist/lib/pagination.d.ts.map

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

package/dist/lib/pagination.js

@@ -0,0 +1,189 @@
+import { asc, desc, sql } from 'drizzle-orm';
+import { z } from 'zod';
+import { AppError } from './errors.js';
+/**
+ * Cursor pagination from `api.md`: `?limit=` and `?cursor=`, an opaque cursor,
+ * and `{ data, next_cursor }` on the wire.
+ *
+ * The cursor is a keyset rather than an offset. It carries the sort value and id
+ * of the last row on the page, so a page boundary stays put when rows are
+ * inserted or deleted underneath a client. Offsets skip and repeat rows when that
+ * happens, which for a CRM that agents write to is not a rare case.
+ *
+ * A cursor is bound to the sort it was issued under. Reusing one against a
+ * different `?sort=` is a client bug, and it is reported as one rather than
+ * silently paging through a different order.
+ */
+export const DEFAULT_PAGE_SIZE = 50;
+export const MAX_PAGE_SIZE = 200;
+/** The cursor payload. It is client-supplied, so it is parsed, never trusted. */
+const cursorSchema = z.strictObject({
+    sort: z.string().min(1),
+    value: z.string(),
+    id: z.string().min(1),
+});
+function invalidCursor(reason) {
+    return AppError.validationFailed('That cursor is not one this API issued', [
+        { field: 'cursor', message: reason },
+    ]);
+}
+export function textSort(column, valueOf) {
+    return { column, valueOf, parse: (value) => value };
+}
+export function integerSort(column, valueOf) {
+    return {
+        column,
+        valueOf: (record) => String(valueOf(record)),
+        parse: (value) => {
+            const parsed = Number(value);
+            if (!Number.isInteger(parsed)) {
+                throw invalidCursor('Its position is not a whole number');
+            }
+            return parsed;
+        },
+    };
+}
+export function timestampSort(column, valueOf) {
+    return {
+        column,
+        valueOf: (record) => valueOf(record).toISOString(),
+        parse: (value) => {
+            const parsed = new Date(value);
+            if (Number.isNaN(parsed.getTime())) {
+                throw invalidCursor('Its position is not a timestamp');
+            }
+            return parsed;
+        },
+    };
+}
+function encodeCursor(sort, value, id) {
+    return Buffer.from(JSON.stringify({ sort, value, id }), 'utf8').toString('base64url');
+}
+function decodeCursor(raw) {
+    let payload;
+    try {
+        payload = JSON.parse(Buffer.from(raw, 'base64url').toString('utf8'));
+    }
+    catch {
+        // Base64 and JSON both refuse the same way here: the string did not come
+        // from `encodeCursor`. The client cannot act on which of the two failed.
+        throw invalidCursor('It is not readable');
+    }
+    const parsed = cursorSchema.safeParse(payload);
+    if (!parsed.success) {
+        throw invalidCursor('It does not carry a position');
+    }
+    return parsed.data;
+}
+/**
+ * Reads `?limit=` against the `api.md` range.
+ *
+ * Exported for the endpoints that take the same parameter without being paged
+ * lists. The dashboard is the case: it caps several embedded lists at once and
+ * issues no cursor, but the ceiling a caller may ask for is the same one.
+ *
+ * @throws AppError 422 for anything but a whole number in range.
+ */
+export function readPageSize(raw) {
+    if (raw === undefined) {
+        return DEFAULT_PAGE_SIZE;
+    }
+    const limit = Number(raw);
+    if (!Number.isInteger(limit) || limit < 1 || limit > MAX_PAGE_SIZE) {
+        throw AppError.validationFailed('That page size is out of range', [
+            { field: 'limit', message: `Use a whole number from 1 to ${String(MAX_PAGE_SIZE)}` },
+        ]);
+    }
+    return limit;
+}
+/**
+ * Reads `?limit=`, `?sort=` and `?cursor=` into a window a repository can apply.
+ *
+ * @param defaultSort The resource's own default, `-created_at` style. Naming a
+ *   field the resource does not declare is a programming error, not a request
+ *   error, so it throws rather than producing a 422.
+ * @throws AppError 422 for an out-of-range limit, an undocumented sort field, or
+ *   a cursor that is unreadable or belongs to a different sort order.
+ */
+export function readListWindow(query, fields, defaultSort) {
+    const sort = query.sort ?? defaultSort;
+    const descending = sort.startsWith('-');
+    const name = descending ? sort.slice(1) : sort;
+    const field = fields[name];
+    if (field === undefined) {
+        const documented = Object.keys(fields).sort().join(', ');
+        if (query.sort === undefined) {
+            throw new Error(`Default sort "${defaultSort}" is not one of: ${documented}`);
+        }
+        throw AppError.validationFailed('That sort field is not available on this resource', [
+            { field: 'sort', message: `Sort by one of: ${documented}` },
+        ]);
+    }
+    const position = (() => {
+        if (query.cursor === undefined) {
+            return undefined;
+        }
+        const decoded = decodeCursor(query.cursor);
+        if (decoded.sort !== sort) {
+            throw invalidCursor(`It was issued for sort=${decoded.sort}`);
+        }
+        return { value: field.parse(decoded.value), id: decoded.id };
+    })();
+    const limit = readPageSize(query.limit);
+    return { limit, fetchLimit: limit + 1, sort, field, descending, position };
+}
+/**
+ * The keyset predicate: everything after the cursor's row in the window's order.
+ *
+ * Values go through `sql.param` with their own column as the encoder. A bare
+ * `${value}` in a template reaches the driver unconverted, and postgres.js has no
+ * column to infer from, so a `Date` arrives where it wants a string.
+ *
+ * @returns undefined on the first page, where there is nothing to seek past.
+ */
+export function keysetCondition(window, idColumn) {
+    if (window.position === undefined) {
+        return undefined;
+    }
+    const { column } = window.field;
+    const after = sql.param(window.position.value, column);
+    const afterId = sql.param(window.position.id, idColumn);
+    return window.descending
+        ? sql `(${column} < ${after} or (${column} = ${after} and ${idColumn} < ${afterId}))`
+        : sql `(${column} > ${after} or (${column} = ${after} and ${idColumn} > ${afterId}))`;
+}
+/**
+ * The ordering, id included. Without the id tiebreak two rows sharing a sort
+ * value could straddle a page boundary in either order, and one of them would be
+ * lost or repeated.
+ */
+export function orderByWindow(window, idColumn) {
+    const direction = window.descending ? desc : asc;
+    return [direction(window.field.column), direction(idColumn)];
+}
+/**
+ * Trims the extra row a repository fetched and turns it into a next cursor.
+ *
+ * @param rows Up to `window.fetchLimit` rows, in the window's order.
+ */
+export function toPage(rows, window, idOf) {
+    if (rows.length < window.fetchLimit) {
+        return { items: rows, nextCursor: null };
+    }
+    const items = rows.slice(0, window.limit);
+    const last = items.at(-1);
+    if (last === undefined) {
+        throw new Error('unreachable: a full page cannot be empty');
+    }
+    return { items, nextCursor: encodeCursor(window.sort, window.field.valueOf(last), idOf(last)) };
+}
+/**
+ * Re-shapes the items of a page, leaving the cursor alone.
+ *
+ * A service pages over stored rows and answers with views, and the cursor is
+ * built from the row it came from, not from what the caller is handed back.
+ */
+export function mapPage(page, render) {
+    return { items: page.items.map(render), nextCursor: page.nextCursor };
+}
+//# sourceMappingURL=pagination.js.map

package/dist/lib/pagination.js.map

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

package/dist/lib/passwords.d.ts

@@ -0,0 +1,32 @@
+import { MINIMUM_PASSWORD_LENGTH } from '@kelpie/schemas';
+/**
+ * Password hashing. Argon2id, the parameters the library defaults to, which
+ * follow the OWASP recommendation at time of writing.
+ *
+ * The algorithm and its parameters are embedded in the hash string, so raising
+ * the cost later does not invalidate existing hashes: they verify with the
+ * parameters they were made with, and `needsRehash` says when to upgrade one.
+ */
+/**
+ * Rejected before hashing. Argon2 will happily hash an empty string.
+ *
+ * The number lives in `@kelpie/schemas` because the browser's change-password
+ * form states the rule before submitting, and two copies would be two rules.
+ * Re-exported here so callers keep reading it off the module that enforces it.
+ */
+export { MINIMUM_PASSWORD_LENGTH };
+export declare class WeakPasswordError extends Error {
+    constructor(message: string);
+}
+/**
+ * @throws WeakPasswordError when the password is too short to be worth hashing.
+ */
+export declare function hashPassword(plaintext: string): Promise<string>;
+/**
+ * Constant-time within argon2 itself. Returns false rather than throwing on a
+ * malformed stored hash, because a corrupted row must not become a login bypass
+ * or a 500 that distinguishes it from a wrong password.
+ */
+export declare function verifyPassword(storedHash: string, plaintext: string): Promise<boolean>;
+export declare function isPasswordStrongEnough(plaintext: string): boolean;
+//# sourceMappingURL=passwords.d.ts.map

package/dist/lib/passwords.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"passwords.d.ts","sourceRoot":"","sources":["../../src/lib/passwords.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAA;AAGzD;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,OAAO,EAAE,uBAAuB,EAAE,CAAA;AAElC,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAMrE;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO5F;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEjE"}

package/dist/lib/passwords.js

@@ -0,0 +1,51 @@
+import { MINIMUM_PASSWORD_LENGTH } from '@kelpie/schemas';
+import { hash, verify } from '@node-rs/argon2';
+/**
+ * Password hashing. Argon2id, the parameters the library defaults to, which
+ * follow the OWASP recommendation at time of writing.
+ *
+ * The algorithm and its parameters are embedded in the hash string, so raising
+ * the cost later does not invalidate existing hashes: they verify with the
+ * parameters they were made with, and `needsRehash` says when to upgrade one.
+ */
+/**
+ * Rejected before hashing. Argon2 will happily hash an empty string.
+ *
+ * The number lives in `@kelpie/schemas` because the browser's change-password
+ * form states the rule before submitting, and two copies would be two rules.
+ * Re-exported here so callers keep reading it off the module that enforces it.
+ */
+export { MINIMUM_PASSWORD_LENGTH };
+export class WeakPasswordError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WeakPasswordError';
+    }
+}
+/**
+ * @throws WeakPasswordError when the password is too short to be worth hashing.
+ */
+export async function hashPassword(plaintext) {
+    if (plaintext.length < MINIMUM_PASSWORD_LENGTH) {
+        throw new WeakPasswordError(`Password must be at least ${MINIMUM_PASSWORD_LENGTH} characters`);
+    }
+    return hash(plaintext);
+}
+/**
+ * Constant-time within argon2 itself. Returns false rather than throwing on a
+ * malformed stored hash, because a corrupted row must not become a login bypass
+ * or a 500 that distinguishes it from a wrong password.
+ */
+export async function verifyPassword(storedHash, plaintext) {
+    try {
+        return await verify(storedHash, plaintext);
+    }
+    catch {
+        // A hash argon2 cannot parse is not a match. The row is corrupt, not correct.
+        return false;
+    }
+}
+export function isPasswordStrongEnough(plaintext) {
+    return plaintext.length >= MINIMUM_PASSWORD_LENGTH;
+}
+//# sourceMappingURL=passwords.js.map

package/dist/lib/passwords.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"passwords.js","sourceRoot":"","sources":["../../src/lib/passwords.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAE9C;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,OAAO,EAAE,uBAAuB,EAAE,CAAA;AAElC,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAA;IACjC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,SAAiB;IAClD,IAAI,SAAS,CAAC,MAAM,GAAG,uBAAuB,EAAE,CAAC;QAC/C,MAAM,IAAI,iBAAiB,CAAC,6BAA6B,uBAAuB,aAAa,CAAC,CAAA;IAChG,CAAC;IAED,OAAO,IAAI,CAAC,SAAS,CAAC,CAAA;AACxB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,UAAkB,EAAE,SAAiB;IACxE,IAAI,CAAC;QACH,OAAO,MAAM,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,CAAA;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,8EAA8E;QAC9E,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,SAAiB;IACtD,OAAO,SAAS,CAAC,MAAM,IAAI,uBAAuB,CAAA;AACpD,CAAC"}

package/dist/lib/search.d.ts

@@ -0,0 +1,11 @@
+import type { Column, SQL } from 'drizzle-orm';
+/** Wraps a search term as a LIKE pattern, escaping anything the user did not mean as a wildcard. */
+export declare function containsPattern(term: string): string;
+/**
+ * True when any element of a `text[]` column matches the pattern.
+ *
+ * `tags @> '{…}'` would only find whole-tag equality, and the filter box is a
+ * substring filter.
+ */
+export declare function arrayContainsPattern(column: Column, pattern: string): SQL;
+//# sourceMappingURL=search.d.ts.map

package/dist/lib/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/lib/search.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,aAAa,CAAA;AAc9C,oGAAoG;AACpG,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,GAAG,CAEzE"}

package/dist/lib/search.js

@@ -0,0 +1,25 @@
+import { sql } from 'drizzle-orm';
+/**
+ * The `?q=` free-text filter from `api.md`: a case-insensitive substring match
+ * over the fields the mockup's `FilterBar` matches for that object.
+ *
+ * Substring matching, not full-text search. A user typing three characters into a
+ * filter box expects to see partial words, which `to_tsquery` will not give them.
+ * Search across resources is its own feature with its own index.
+ */
+/** `%`, `_` and `\` steer LIKE. A user typing one means the character, not the pattern. */
+const LIKE_WILDCARDS = /[\\%_]/gu;
+/** Wraps a search term as a LIKE pattern, escaping anything the user did not mean as a wildcard. */
+export function containsPattern(term) {
+    return `%${term.trim().replace(LIKE_WILDCARDS, (match) => `\\${match}`)}%`;
+}
+/**
+ * True when any element of a `text[]` column matches the pattern.
+ *
+ * `tags @> '{…}'` would only find whole-tag equality, and the filter box is a
+ * substring filter.
+ */
+export function arrayContainsPattern(column, pattern) {
+    return sql `exists (select 1 from unnest(${column}) as element where element ilike ${pattern})`;
+}
+//# sourceMappingURL=search.js.map

package/dist/lib/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/lib/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAA;AAGjC;;;;;;;GAOG;AAEH,2FAA2F;AAC3F,MAAM,cAAc,GAAG,UAAU,CAAA;AAEjC,oGAAoG;AACpG,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,GAAG,CAAA;AAC5E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAc,EAAE,OAAe;IAClE,OAAO,GAAG,CAAA,gCAAgC,MAAM,oCAAoC,OAAO,GAAG,CAAA;AAChG,CAAC"}

package/dist/lib/secrets.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+/** Thrown when sealed text cannot be read back: wrong key, or tampered ciphertext. */
+export declare class SecretDecryptionError extends Error {
+    constructor(reason: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface SecretCipher {
+    /** @returns `v1.<base64url iv>.<base64url tag>.<base64url ciphertext>`, safe to store as text. */
+    seal(plaintext: string): string;
+    /**
+     * Reads a stored value, trying the current key and then the previous one.
+     *
+     * @throws SecretDecryptionError when the text is malformed, tampered with, or
+     *   sealed under a key this cipher does not hold.
+     */
+    open(sealed: string): string;
+    /**
+     * The same value sealed under the current key, or undefined when it already is.
+     *
+     * This is what makes a re-seal pass idempotent: it is the only way to tell
+     * "readable because it is current" from "readable because the previous key is
+     * still configured", which `open` deliberately hides from everything else.
+     *
+     * @throws SecretDecryptionError when neither key opens it.
+     */
+    reseal(sealed: string): string | undefined;
+}
+/**
+ * The environment slice a module needs to build a cipher. Modules validate it
+ * through `context.config`, so a missing or malformed key stops boot with the
+ * module named rather than failing on the first delivery attempt.
+ */
+export declare const secretEncryptionConfigSchema: z.ZodObject<{
+    SECRET_ENCRYPTION_KEY: z.ZodString;
+    SECRET_ENCRYPTION_KEY_PREVIOUS: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SecretEncryptionConfig = z.infer<typeof secretEncryptionConfigSchema>;
+export declare function createSecretCipher(config: SecretEncryptionConfig): SecretCipher;
+//# sourceMappingURL=secrets.d.ts.map

package/dist/lib/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../src/lib/secrets.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AA+BvB,sFAAsF;AACtF,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAOxD;CACF;AAED,MAAM,WAAW,YAAY;IAC3B,kGAAkG;IAClG,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAA;IAC/B;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAA;IAC5B;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CAC3C;AAID;;;;GAIG;AACH,eAAO,MAAM,4BAA4B;;;iBAmBvC,CAAA;AAMF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAqEjF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,sBAAsB,GAAG,YAAY,CAuD/E"}

package/dist/lib/secrets.js

@@ -0,0 +1,152 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { z } from 'zod';
+/**
+ * Reversible storage for secrets the service itself has to use again.
+ *
+ * Distinct from `lib/tokens.ts`, and the difference is what a secret is *for*.
+ * A session cookie or an API key is only ever compared against, so it is stored
+ * as a SHA-256 hash and nothing can read it back. A webhook signing secret is
+ * different: `api.md` computes the delivery signature *with* it, and the
+ * receiver holds the plaintext we showed them once, so the service must be able
+ * to produce the same bytes months later. Hashing it would make signing
+ * impossible; storing it bare would put every workspace's signing secret in any
+ * database dump.
+ *
+ * `schema.md` already anticipates this for `agent_registrations.auth_header_encrypted`,
+ * and `modules.md` for integration connection records. They share this module.
+ */
+/** AES-256-GCM: authenticated, so a tampered ciphertext fails rather than decodes to noise. */
+const ALGORITHM = 'aes-256-gcm';
+const KEY_BYTES = 32;
+/** 96 bits, the size GCM is specified for. A fresh one per seal, never reused. */
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+/**
+ * Marks the format so a future scheme can be introduced without guessing at
+ * what an existing row holds. Rotation reads the version, not the length.
+ */
+const FORMAT_VERSION = 'v1';
+/** Thrown when sealed text cannot be read back: wrong key, or tampered ciphertext. */
+export class SecretDecryptionError extends Error {
+    constructor(reason, options) {
+        super(`Could not decrypt a stored secret: ${reason}`);
+        this.name = 'SecretDecryptionError';
+        if (options?.cause !== undefined) {
+            this.cause = options.cause;
+        }
+    }
+}
+const KEY_MESSAGE = `must be ${String(KEY_BYTES)} bytes of base64, e.g. from: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"`;
+/**
+ * The environment slice a module needs to build a cipher. Modules validate it
+ * through `context.config`, so a missing or malformed key stops boot with the
+ * module named rather than failing on the first delivery attempt.
+ */
+export const secretEncryptionConfigSchema = z.object({
+    SECRET_ENCRYPTION_KEY: z
+        .string()
+        .refine((value) => decodeKey(value) !== undefined, { message: KEY_MESSAGE }),
+    /**
+     * The key being rotated away from. Optional, and only set while a rotation is
+     * in progress: `open` falls back to it, so the service keeps signing
+     * deliveries between the moment the new key is deployed and the moment
+     * `npm run reseal` finishes. Remove it once that pass reports nothing left.
+     *
+     * Blank counts as absent. An operator ending a rotation empties the line far
+     * more often than they delete it, and refusing to boot over that would punish
+     * the tidy step of the procedure.
+     */
+    SECRET_ENCRYPTION_KEY_PREVIOUS: z
+        .string()
+        .refine((value) => isBlank(value) || decodeKey(value) !== undefined, { message: KEY_MESSAGE })
+        .optional(),
+});
+function isBlank(value) {
+    return value.trim().length === 0;
+}
+/** @returns The key bytes, or undefined when the value is not base64 of exactly `KEY_BYTES`. */
+function decodeKey(value) {
+    // Buffer.from is lenient: it ignores what it cannot decode rather than
+    // throwing, so the length check is the whole validation. A 64-character hex
+    // key decodes to 48 bytes and is rejected here rather than silently truncated.
+    const decoded = Buffer.from(value, 'base64');
+    return decoded.length === KEY_BYTES ? decoded : undefined;
+}
+/** @throws SecretDecryptionError when the text is not a `v1` sealed value. */
+function parseSealed(sealed) {
+    const [version, rawIv, rawTag, rawCiphertext] = sealed.split('.');
+    if (version !== FORMAT_VERSION || rawIv === undefined || rawTag === undefined || rawCiphertext === undefined) {
+        throw new SecretDecryptionError('the stored value is not in the expected format');
+    }
+    const iv = Buffer.from(rawIv, 'base64url');
+    const tag = Buffer.from(rawTag, 'base64url');
+    if (iv.length !== IV_BYTES || tag.length !== TAG_BYTES) {
+        throw new SecretDecryptionError('the stored value has a malformed header');
+    }
+    return { iv, tag, ciphertext: Buffer.from(rawCiphertext, 'base64url') };
+}
+/** @returns The plaintext, or undefined when this key is not the one it was sealed with. */
+function openWith(key, parts) {
+    const decipher = createDecipheriv(ALGORITHM, key, parts.iv);
+    decipher.setAuthTag(parts.tag);
+    try {
+        return Buffer.concat([decipher.update(parts.ciphertext), decipher.final()]).toString('utf8');
+    }
+    catch {
+        // GCM raises here when the tag does not match, which means either the wrong
+        // key or a modified row. Undefined rather than a throw because the caller is
+        // working through a list of keys and a miss is expected on all but one.
+        return undefined;
+    }
+}
+/** @throws Error when the value is not `KEY_BYTES` of base64. */
+function requireKey(name, value) {
+    const key = decodeKey(value);
+    if (key === undefined) {
+        throw new Error(`${name} must be ${String(KEY_BYTES)} bytes of base64`);
+    }
+    return key;
+}
+export function createSecretCipher(config) {
+    const current = requireKey('SECRET_ENCRYPTION_KEY', config.SECRET_ENCRYPTION_KEY);
+    const previousValue = config.SECRET_ENCRYPTION_KEY_PREVIOUS;
+    // Blank counts as absent, which is how an operator normally ends a rotation.
+    const previous = previousValue === undefined || isBlank(previousValue)
+        ? undefined
+        : requireKey('SECRET_ENCRYPTION_KEY_PREVIOUS', previousValue);
+    /** Current first: the common case is a value that needs no fallback at all. */
+    const keys = previous === undefined ? [current] : [current, previous];
+    function seal(plaintext) {
+        const iv = randomBytes(IV_BYTES);
+        const cipher = createCipheriv(ALGORITHM, current, iv);
+        const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+        return [
+            FORMAT_VERSION,
+            iv.toString('base64url'),
+            cipher.getAuthTag().toString('base64url'),
+            ciphertext.toString('base64url'),
+        ].join('.');
+    }
+    function open(sealed) {
+        const parts = parseSealed(sealed);
+        for (const key of keys) {
+            const plaintext = openWith(key, parts);
+            if (plaintext !== undefined) {
+                return plaintext;
+            }
+        }
+        throw new SecretDecryptionError(previous === undefined
+            ? 'it was sealed with a different key, or has been altered'
+            : 'neither the current nor the previous key opens it, or it has been altered');
+    }
+    function reseal(sealed) {
+        if (openWith(current, parseSealed(sealed)) !== undefined) {
+            return undefined;
+        }
+        // Not readable under the current key, so `open` either finds it under the
+        // previous one or throws, which is exactly the caller's answer either way.
+        return seal(open(sealed));
+    }
+    return { seal, open, reseal };
+}
+//# sourceMappingURL=secrets.js.map