@bevel-software/platform-core-backend 0.22.0 → 0.24.0

package/dist/modules/workspace/zip-entry-rules.js

@@ -0,0 +1,154 @@
+import { inflateRawSync } from 'node:zlib';
+import { validateFilename } from '@bevel-software/platform-shared';
+import { GitInternalsError } from '../../shared/domain-errors.js';
+import { hasGitInternalsSegment } from '../../shared/git-internals.js';
+/**
+ * What an archive's entry NAMES are allowed to be, as one set of rules two
+ * surfaces ask: `unzip` (a .zip already in the workspace) and
+ * `apply_file_upload` (a .zip the agent sent to the upload route). Both land
+ * bytes an agent never typed at paths the archive chose, so both have to judge
+ * the same names the same way — and they did not, for as long as the rules
+ * lived inside `WorkspaceService.unzipFile` as three inline blocks.
+ *
+ * NAMES, and how an entry's BYTES are read ({@link readZipEntry}) — the two
+ * things decidable from the archive alone. Whether a target sits behind a
+ * symbolic link already on disk, whether the caller may write there, and what
+ * is already at the path are facts about a workspace, so each surface asks
+ * those where its own writes land.
+ */
+/**
+ * The entries an archive from macOS carries that nobody asked for: the
+ * resource-fork sidecar tree and the Finder's own index. SILENTLY dropped
+ * rather than reported — they are not the caller's content and a list of
+ * refusals about them says nothing.
+ */
+export function isZipNoiseEntry(rawName) {
+    return (rawName.startsWith('__MACOSX/') ||
+        rawName === '__MACOSX' ||
+        rawName.endsWith('/.DS_Store') ||
+        rawName === '.DS_Store' ||
+        /(^|\/)\._/.test(rawName));
+}
+/**
+ * An entry's name with separators in the one spelling the rules read. A zip
+ * written on Windows may use `\`, which every check below (and every path
+ * built from the result) would otherwise read as part of a single segment.
+ */
+export function zipEntryName(entryName) {
+    return entryName.replace(/\\/g, '/');
+}
+/** The path segments `rawName` names, with a trailing slash and empty parts dropped. */
+export function zipEntrySegments(rawName) {
+    return rawName
+        .replace(/\/+$/, '')
+        .split('/')
+        .filter((s) => s.length > 0);
+}
+/**
+ * Why `rawName` may not be landed at all — the reason a caller reports beside
+ * the entry — or null when the name is one a workspace path can be built from.
+ *
+ * Three rules, in the order that makes each refusal say the most useful thing:
+ * a path that climbs out or is anchored at the root is invalid whatever its
+ * segments are; the git folder is refused in every spelling, because an
+ * archive must not be a way to write what git reads as its own metadata; and
+ * then each segment has to be a name a filesystem on any of the three
+ * operating systems keeps intact (`validateFilename`).
+ */
+export function zipEntryNameRefusal(rawName) {
+    if (!rawName || rawName.startsWith('/') || /(^|\/)\.\.($|\/)/.test(rawName))
+        return 'Invalid path';
+    if (hasGitInternalsSegment(rawName))
+        return new GitInternalsError().message;
+    for (const segment of zipEntrySegments(rawName)) {
+        const reason = validateFilename(segment);
+        if (reason)
+            return reason;
+    }
+    return null;
+}
+/**
+ * Whether a zip entry is a symbolic LINK rather than a file or a folder.
+ *
+ * A zip stores a link as an ordinary member whose bytes are the link's target
+ * text and whose unix mode (the high half of the external attributes) carries
+ * `S_IFLNK`. A reader that ignores the mode writes the target text out as a
+ * regular file — content nobody sent, under a name that was meant to point
+ * somewhere. `apply_file_upload` refuses such an entry outright; the entry is
+ * not a file, so there are no bytes of the caller's to land.
+ */
+export function isSymlinkZipEntry(entry) {
+    const attr = entry.header?.attr ?? entry.attr ?? 0;
+    if (!Number.isFinite(attr) || attr <= 0)
+        return false;
+    // The external attributes' high 16 bits are the unix mode when the archive
+    // was written on a unix host; `S_IFMT & mode === S_IFLNK` is the link bit.
+    return ((attr >>> 16) & 0o170000) === 0o120000;
+}
+/** A zip's compression method for DEFLATE, the only one that can expand. */
+const ZIP_METHOD_DEFLATED = 8;
+/**
+ * Read one entry's bytes, inflating NO MORE than `budget` of them.
+ *
+ * The one read both surfaces use, because the bound is the whole point and it
+ * has a hole when each surface writes it itself. An entry's header DECLARES its
+ * uncompressed size, and the reader caps the inflation at that — but only when
+ * the size it declares is above zero. An entry that declares zero is inflated
+ * with no cap at all, so "check the declared size against the budget, then
+ * read" passes a 20 KB archive that expands to 20 MB, and a 50 MB one that
+ * expands to tens of gigabytes in a single call, before any check on the bytes
+ * that arrived has run. A thousandfold is what deflate does to a run of one
+ * byte; the header saying "empty" was the only thing standing in front of it.
+ *
+ * So the declared size is never the only bound:
+ *
+ *  - an entry declaring more than `budget` is refused unread;
+ *  - a DEFLATED entry declaring ZERO with a stream of its own is inflated here,
+ *    capped at a single byte. An empty file compressed with deflate is exactly
+ *    this shape (a two-byte stream that inflates to nothing) and is read as the
+ *    empty file it is; anything that inflates to a byte or more contradicts its
+ *    own header and is refused;
+ *  - every other entry is read by the archive reader, which caps the inflation
+ *    at the declared size this function has just held against the budget, and
+ *    the bytes that arrive are measured again.
+ *
+ * A read that throws — a failed checksum, a stream longer than it declared, an
+ * unknown method — is that entry's refusal, not the whole archive's: one bad
+ * member must not cost the caller the others.
+ */
+export function readZipEntry(entry, budget) {
+    const { size: declared, compressedSize, method } = entry.header;
+    if (declared > budget)
+        return { ok: false, reason: 'too_large' };
+    if (declared === 0 && method === ZIP_METHOD_DEFLATED && compressedSize > 0) {
+        let inflated;
+        try {
+            inflated = inflateRawSync(entry.getCompressedData(), { maxOutputLength: 1 });
+        }
+        catch (err) {
+            // Past the one-byte cap, or not a deflate stream at all: either way it
+            // is not the empty file its header says it is.
+            return { ok: false, reason: 'unreadable', detail: declaresEmptyButIsNot(err) };
+        }
+        if (inflated.byteLength > 0)
+            return { ok: false, reason: 'unreadable', detail: declaresEmptyButIsNot() };
+        return { ok: true, data: inflated };
+    }
+    let data;
+    try {
+        data = entry.getData();
+    }
+    catch (err) {
+        return { ok: false, reason: 'unreadable', detail: err instanceof Error ? err.message : String(err) };
+    }
+    if (data.byteLength > budget)
+        return { ok: false, reason: 'too_large' };
+    return { ok: true, data };
+}
+function declaresEmptyButIsNot(err) {
+    const outputLimit = err?.code === 'ERR_BUFFER_TOO_LARGE';
+    return err === undefined || outputLimit
+        ? 'its header declares an empty file, but it holds content'
+        : `its header declares an empty file, and its content could not be read (${err instanceof Error ? err.message : String(err)})`;
+}
+//# sourceMappingURL=zip-entry-rules.js.map

package/dist/modules/workspace/zip-entry-rules.js.map

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

package/dist/modules/write-access/write-access.d.ts

@@ -0,0 +1,60 @@
+import express, { type RequestHandler } from 'express';
+/**
+ * Whether the deployment may be CHANGED right now. The seam a host that
+ * sells seats needs for a workspace that has more people on it than its plan
+ * allows: nobody is removed and everyone can still sign in and read, but
+ * nothing can be edited until an admin brings the count down or the plan up
+ * — the way Notion handles a lapsed workspace.
+ *
+ * Core is always writable. The port is asked on every request that would
+ * change something (a mutating HTTP route, a write tool), so a host answers
+ * from something cheap — its own cached view of the plan.
+ */
+export type WriteAccessVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+export interface IWriteAccess {
+    canWrite(): Promise<WriteAccessVerdict>;
+    /**
+     * Paths of the host's own routes that must stay usable while the
+     * deployment is read-only — above all, the ones that END it (buying
+     * seats, the billing portal). Matched as prefixes of the request path.
+     */
+    readonly alwaysWritablePaths?: readonly string[];
+}
+/** Core's default: always writable. */
+export declare const alwaysWritable: IWriteAccess;
+/** The `code` a refused write answers with, so a client can tell it from a permission error. */
+export declare const READ_ONLY_CODE = "workspace_read_only";
+/**
+ * Whether a request may go ahead while the deployment is read-only, without asking.
+ *
+ * Judged on the path in LOWER CASE, because that is how the router reads
+ * it: routes match whatever the letter case, so `/API/workspace/…` reaches
+ * the same handler as `/api/workspace/…`. Judged as written, it would be
+ * outside the gated namespace and walk past the gate.
+ */
+export declare function isAlwaysWritable(method: string, path: string, hostPaths?: readonly string[]): boolean;
+/**
+ * Refuse every change to the deployment while the port says it is
+ * read-only, with a 403 the app recognises by {@link READ_ONLY_CODE}.
+ * Mounted ahead of every route under `/api`; a request the port is not
+ * asked about costs nothing. A port that fails is treated as writable —
+ * a billing lookup that is down must not freeze every workspace.
+ */
+export declare function createWriteGateMiddleware(writeAccess: IWriteAccess): RequestHandler;
+/**
+ * The verdict for a write tool, the tool layer's half of the gate: `null`
+ * when it may run, the refusal otherwise. Same failure rule as the HTTP gate.
+ */
+export declare function refuseWriteTool(writeAccess: IWriteAccess): Promise<string | null>;
+/**
+ * GET /api/write-access — whether the deployment can be changed right now,
+ * and if not, the host's words for why. The app reads it to say so once, in
+ * a banner, instead of letting every save fail on its own.
+ */
+export declare function createWriteAccessRoutes(writeAccess: IWriteAccess): express.Router;
+//# sourceMappingURL=write-access.d.ts.map

package/dist/modules/write-access/write-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-access.d.ts","sourceRoot":"","sources":["../../../src/modules/write-access/write-access.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,EAAE,EAAE,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAKvD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/E,MAAM,WAAW,YAAY;IAC3B,QAAQ,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClD;AAED,uCAAuC;AACvC,eAAO,MAAM,cAAc,EAAE,YAE5B,CAAC;AAEF,gGAAgG;AAChG,eAAO,MAAM,cAAc,wBAAwB,CAAC;AA8CpD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,SAAS,MAAM,EAAO,GAAG,OAAO,CAQzG;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,YAAY,GAAG,cAAc,CAcnF;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,WAAW,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASvF;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAWjF"}

package/dist/modules/write-access/write-access.js

@@ -0,0 +1,129 @@
+import express from 'express';
+import { logger } from '../../shared/logging.js';
+const log = logger('write-access');
+/** Core's default: always writable. */
+export const alwaysWritable = {
+    canWrite: async () => ({ ok: true }),
+};
+/** The `code` a refused write answers with, so a client can tell it from a permission error. */
+export const READ_ONLY_CODE = 'workspace_read_only';
+const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+/**
+ * The mutating routes that stay open while the deployment is read-only.
+ * EVERY OTHER mutating route under `/api` is refused, so a route added
+ * later is read-only until someone decides otherwise — the safe default for
+ * a list nobody re-reads when adding a route.
+ *
+ * What stays open, and why:
+ *  - Signing in and out of everything: sessions, agent connections and
+ *    their keys. A read-only workspace is still one people read.
+ *  - Account administration: the way an admin brings the number of people
+ *    down. Erasing an account with `removeFromAccess` commits to the
+ *    knowledge base, and that commit is part of the same act.
+ *  - The tool surface: every tool call is judged by the tool layer itself,
+ *    which knows a read tool from a write tool (see `toolHandler`); the MCP
+ *    endpoint only relays to it.
+ *  - Deployment setup, tool secrets and pulling remote changes in: the
+ *    deployment's configuration, not its content, and what an admin needs
+ *    to keep it working.
+ *  - Requests that are POST only because they carry a body: permission
+ *    queries, previews, probes, focus and heartbeat signals, fetching
+ *    remotes, accepting a review baseline. None of them changes content.
+ */
+const ALWAYS_WRITABLE = [
+    /^\/api\/auth\//,
+    /^\/api\/mcp(\/|$)/,
+    /^\/api\/agent\//,
+    /^\/api\/admin\/accounts(\/|$)/,
+    /^\/api\/admin\/connection-keys\//,
+    /^\/api\/audit\//,
+    /^\/api\/sync(\/|$)/,
+    /^\/api\/setup\//,
+    /^\/api\/secrets\//,
+    /^\/api\/admin\/github-facade\//,
+    /^\/api\/workspace\/[^/]+\/access\/batch$/,
+    /^\/api\/workspace\/[^/]+\/review\/accept$/,
+    /^\/api\/workspace\/[^/]+\/flush$/,
+    /^\/api\/workspace\/[^/]+\/workflow\/refresh-remotes$/,
+    /^\/api\/workspace\/[^/]+\/workflow\/locks\/heartbeat$/,
+    /^\/api\/events\/[^/]+\/focus$/,
+    /^\/api\/tools\/preview$/,
+];
+/**
+ * Whether a request may go ahead while the deployment is read-only, without asking.
+ *
+ * Judged on the path in LOWER CASE, because that is how the router reads
+ * it: routes match whatever the letter case, so `/API/workspace/…` reaches
+ * the same handler as `/api/workspace/…`. Judged as written, it would be
+ * outside the gated namespace and walk past the gate.
+ */
+export function isAlwaysWritable(method, path, hostPaths = []) {
+    if (!MUTATING_METHODS.has(method.toUpperCase()))
+        return true;
+    const asRouted = path.toLowerCase();
+    if (asRouted !== '/api' && !asRouted.startsWith('/api/'))
+        return true;
+    return (ALWAYS_WRITABLE.some((rule) => rule.test(asRouted)) ||
+        hostPaths.some((prefix) => asRouted.startsWith(prefix.toLowerCase())));
+}
+/**
+ * Refuse every change to the deployment while the port says it is
+ * read-only, with a 403 the app recognises by {@link READ_ONLY_CODE}.
+ * Mounted ahead of every route under `/api`; a request the port is not
+ * asked about costs nothing. A port that fails is treated as writable —
+ * a billing lookup that is down must not freeze every workspace.
+ */
+export function createWriteGateMiddleware(writeAccess) {
+    if (writeAccess === alwaysWritable)
+        return (_req, _res, next) => next();
+    return async (req, res, next) => {
+        if (isAlwaysWritable(req.method, req.path, writeAccess.alwaysWritablePaths))
+            return next();
+        let verdict;
+        try {
+            verdict = await writeAccess.canWrite();
+        }
+        catch (err) {
+            log.warn('the write-access port failed; letting the request through:', { err });
+            return next();
+        }
+        if (verdict.ok)
+            return next();
+        res.status(403).json({ error: verdict.message, code: READ_ONLY_CODE });
+    };
+}
+/**
+ * The verdict for a write tool, the tool layer's half of the gate: `null`
+ * when it may run, the refusal otherwise. Same failure rule as the HTTP gate.
+ */
+export async function refuseWriteTool(writeAccess) {
+    if (writeAccess === alwaysWritable)
+        return null;
+    try {
+        const verdict = await writeAccess.canWrite();
+        return verdict.ok ? null : verdict.message;
+    }
+    catch (err) {
+        log.warn('the write-access port failed; letting the tool run:', { err });
+        return null;
+    }
+}
+/**
+ * GET /api/write-access — whether the deployment can be changed right now,
+ * and if not, the host's words for why. The app reads it to say so once, in
+ * a banner, instead of letting every save fail on its own.
+ */
+export function createWriteAccessRoutes(writeAccess) {
+    const router = express.Router();
+    router.get('/write-access', async (_req, res) => {
+        try {
+            const verdict = await writeAccess.canWrite();
+            res.json(verdict.ok ? { writable: true } : { writable: false, message: verdict.message });
+        }
+        catch {
+            res.json({ writable: true });
+        }
+    });
+    return router;
+}
+//# sourceMappingURL=write-access.js.map

package/dist/modules/write-access/write-access.js.map

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

package/dist/shared/column-crypto.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Application-layer encryption for PII columns. Personal data (emails, names,
+ * change-request text) is AES-256-GCM ciphertext in Postgres, so a leaked
+ * dump, an injected query, or a compromised DB credential yields no personal
+ * data — the key lives only in the app's environment. Disk-level encryption
+ * still carries the blanket at-rest claim (git refs, WAL, logs); this layer is
+ * the DB-specific control on top.
+ *
+ * THE KEY BELONGS TO THE DATABASE HANDLE, not to the process. A process that
+ * serves several knowledge bases holds one handle per tenant, each built with
+ * that tenant's own `SECRETS_ENC_KEY` (`createDb(url, { piiKey })`), so a
+ * tenant's rows are sealed under the same key as its stored credentials and
+ * its dump opens, whole, with that one key.
+ *
+ * A drizzle column type is a module-level object and is told nothing about
+ * the handle a statement runs on, so it cannot hold a key. It only MARKS a
+ * value ({@link SealOnWrite}, {@link IndexOnWrite}); the handle's own
+ * connection replaces the mark with ciphertext or a blind index on the way
+ * in, and opens every sealed value on the way out (see `connection.ts`). A
+ * mark that reaches a connection with no key refuses to be written.
+ *
+ * Both keys are HKDF-derived from the handle's key with distinct info
+ * strings, so PII ciphertext and blind indexes are domain-separated from the
+ * secrets-vault key without asking operators to provision a second variable.
+ */
+/** What a database handle seals, opens and indexes personal data with. */
+export interface PiiKeys {
+    /**
+     * Encrypt a value for storage (fresh random IV — NOT equality-comparable).
+     *
+     * The empty string is stored as itself: it carries no personal data, GCM of
+     * an empty plaintext would produce an empty ciphertext segment the blob
+     * parser cannot represent, and columns with a DB-level `DEFAULT ''` then
+     * hold exactly the same representation as an app-written empty value.
+     */
+    seal(plain: string): string;
+    /**
+     * Open a stored value, and SAY whether it opened: a value that is not a
+     * blob is its own plaintext; a blob this key does not open is `ok: false`.
+     * For the callers that must tell "the key does not open this" from a value
+     * — the shape of what {@link read} returns proves nothing, since a
+     * plaintext may itself be shaped like a blob.
+     */
+    open(value: string): {
+        ok: true;
+        plain: string;
+    } | {
+        ok: false;
+    };
+    /**
+     * The lenient read every query result goes through: a blob this key does
+     * not open is handed back as it is, as is anything that is not a blob —
+     * rows written before the encryption release stay readable until the
+     * backfill at start rewrites them.
+     */
+    read(value: string): string;
+    /**
+     * Blind index for equality on an encrypted column: HMAC-SHA256 of the
+     * trimmed, lower-cased value, hex-encoded. Deterministic, so a `*_bidx`
+     * column can carry the unique constraints and lookups that randomized
+     * ciphertext cannot. Reveals only equality, never content.
+     */
+    index(value: string): string;
+}
+/** Derive the personal-data keys from a deployment's (or a tenant's) `SECRETS_ENC_KEY`. */
+export declare function derivePiiKeys(secretsEncKey: string): PiiKeys;
+/**
+ * Every PII ciphertext starts with this marker. An explicit prefix — rather
+ * than recognising ciphertext by its `iv:tag:ct` shape — means legacy
+ * plaintext can never be mistaken for ciphertext (and silently skipped by the
+ * backfill), and lets the backfill find unsealed rows with a plain SQL
+ * predicate instead of scanning every row in the app. Bump the version
+ * segment if the format ever changes.
+ */
+export declare const PII_CIPHERTEXT_PREFIX = "pii:v1:";
+/**
+ * The shape of a PII ciphertext blob, as ONE pattern both Postgres and this
+ * process read: the version prefix followed by base64 segments of the exact
+ * widths GCM produces (12-byte IV → 16 chars, 16-byte tag → 22 chars + `==`).
+ * Lets the backfill find unsealed rows with a `!~` predicate instead of
+ * scanning every row in the app.
+ *
+ * {@link isEncryptedBlob} is built FROM it rather than written beside it. The
+ * two used to be separate spellings of one idea, and they disagreed: the
+ * JavaScript one decoded each part and so took an unpadded tag for a 16-byte
+ * one, which this pattern does not. A value the two disagreed about was
+ * selected by the backfill's SQL as unsealed and then skipped by its
+ * JavaScript as sealed, on every start, and stayed in clear for good. The
+ * pattern uses nothing POSIX and JavaScript read differently.
+ */
+export declare const PII_SEALED_SHAPE_SQL_REGEX = "^pii:v1:[A-Za-z0-9+/]{16}:[A-Za-z0-9+/]{22}==:[A-Za-z0-9+/]+={0,2}$";
+/**
+ * Whether `value` has the shape of a PII ciphertext blob — exactly the values
+ * {@link PII_SEALED_SHAPE_SQL_REGEX} matches in the database, no more and no
+ * fewer. Shape only: whether the configured key OPENS it is `PiiKeys.open`'s
+ * answer, and a plaintext somebody typed in this shape passes here.
+ */
+export declare function isEncryptedBlob(value: string): boolean;
+/**
+ * A value on its way to the database that the handle's connection still has
+ * to turn into what is stored. It is never a storable value itself: `pg`
+ * asks an object how to serialise itself through `toPostgres`, and this one
+ * refuses, so a statement that reaches a connection which did not replace it
+ * — a pool built without `createDb`, or a handle built without a key — fails
+ * instead of writing the plaintext.
+ */
+export declare abstract class PiiParam {
+    readonly plain: string;
+    constructor(plain: string);
+    /** What the handle's keys make of it. */
+    abstract stored(keys: PiiKeys): string;
+    toPostgres(): never;
+}
+/** Plaintext of an {@link encryptedText} column: stored as ciphertext. */
+export declare class SealOnWrite extends PiiParam {
+    stored(keys: PiiKeys): string;
+}
+/** The address a {@link blindIndexText} column is written or compared with: stored as its blind index. */
+export declare class IndexOnWrite extends PiiParam {
+    stored(keys: PiiKeys): string;
+}
+/**
+ * Drizzle column type for encrypted PII text: services read and write
+ * plaintext, the database only ever sees ciphertext. NEVER use an
+ * `encryptedText` column in a WHERE clause or conflict target — the fresh IV
+ * per write means `eq(column, plaintext)` silently matches nothing. Equality
+ * goes through the column's `*_bidx` companion ({@link blindIndexText}).
+ */
+export declare const encryptedText: {
+    (): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
+        name: "";
+        dataType: "custom";
+        columnType: "PgCustomColumn";
+        data: string;
+        driverParam: string;
+        enumValues: undefined;
+    }>;
+    <TConfig extends Record<string, any>>(fieldConfig?: TConfig | undefined): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
+        name: "";
+        dataType: "custom";
+        columnType: "PgCustomColumn";
+        data: string;
+        driverParam: string;
+        enumValues: undefined;
+    }>;
+    <TName extends string>(dbName: TName, fieldConfig?: unknown): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
+        name: TName;
+        dataType: "custom";
+        columnType: "PgCustomColumn";
+        data: string;
+        driverParam: string;
+        enumValues: undefined;
+    }>;
+};
+/**
+ * Drizzle column type for the blind index beside an encrypted column. WRITE
+ * AND COMPARE IT WITH THE VALUE ITSELF — `emailBidx: email`,
+ * `eq(users.emailBidx, email)`, `inArray(users.emailBidx, emails)` — and the
+ * handle's connection stores or binds its index. Reading the column gives the
+ * stored index, which is good for nothing but SQL: writing it back would
+ * index the index, so that is refused. A row copied from another carries the
+ * value its index was made from, not the index.
+ *
+ * Only through drizzle's operators, which bind through the column: a value
+ * interpolated into a raw `sql` template is compared as it is and matches
+ * nothing.
+ */
+export declare const blindIndexText: {
+    (): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
+        name: "";
+        dataType: "custom";
+        columnType: "PgCustomColumn";
+        data: string;
+        driverParam: string;
+        enumValues: undefined;
+    }>;
+    <TConfig extends Record<string, any>>(fieldConfig?: TConfig | undefined): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
+        name: "";
+        dataType: "custom";
+        columnType: "PgCustomColumn";
+        data: string;
+        driverParam: string;
+        enumValues: undefined;
+    }>;
+    <TName extends string>(dbName: TName, fieldConfig?: unknown): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
+        name: TName;
+        dataType: "custom";
+        columnType: "PgCustomColumn";
+        data: string;
+        driverParam: string;
+        enumValues: undefined;
+    }>;
+};
+//# sourceMappingURL=column-crypto.d.ts.map

package/dist/shared/column-crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-crypto.d.ts","sourceRoot":"","sources":["../../src/shared/column-crypto.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,OAAO;IACtB;;;;;;;OAOG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B;;;;;;OAMG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAA;KAAE,CAAC;IACjE;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CAC9B;AAED,2FAA2F;AAC3F,wBAAgB,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAsB5D;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,YAAY,CAAC;AAE/C;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,0BAA0B,wEAAyF,CAAC;AAIjI;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;;;;GAOG;AACH,8BAAsB,QAAQ;IAChB,QAAQ,CAAC,KAAK,EAAE,MAAM;gBAAb,KAAK,EAAE,MAAM;IAElC,yCAAyC;IACzC,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM;IAEtC,UAAU,IAAI,KAAK;CAMpB;AAED,0EAA0E;AAC1E,qBAAa,WAAY,SAAQ,QAAQ;IACvC,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM;CAG9B;AAED,0GAA0G;AAC1G,qBAAa,YAAa,SAAQ,QAAQ;IACxC,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM;CAG9B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;CAaxB,CAAC;AAIH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;CAezB,CAAC"}