@prisma-next/extension-cipherstash 0.0.1

package/src/contract/authoring.ts

@@ -0,0 +1,62 @@
+/**
+ * Authoring contributions for the cipherstash extension.
+ *
+ * Registers `cipherstash.EncryptedString({ equality?, freeTextSearch? })`
+ * as a namespaced PSL type constructor. The same descriptor lowers a
+ * PSL field-type expression like `cipherstash.EncryptedString({ equality:
+ * true })` and a TS factory call like `encryptedString({ equality: true })`
+ * (see `../exports/column-types`) to an identical `ColumnTypeDescriptor`
+ * so PSL- and TS-authored contracts emit byte-identical `contract.json`.
+ *
+ * Mirrors `packages/3-extensions/pgvector/src/contract/authoring.ts`. The
+ * cipherstash variant differs in three respects:
+ *   (a) `cipherstash` is the namespace,
+ *   (b) the constructor takes a single OPTIONAL object argument with two
+ *       optional booleans (so `cipherstash.EncryptedString()`,
+ *       `cipherstash.EncryptedString({})`, and the fully-spelled
+ *       `cipherstash.EncryptedString({ equality: true, freeTextSearch: true })`
+ *       all parse), and
+ *   (c) both flags default to `true` — searchable encryption is the
+ *       legitimate default for an extension whose entire reason for
+ *       existing is to make encrypted columns queryable. Users who want
+ *       storage-only encryption opt out explicitly:
+ *       `cipherstash.EncryptedString({ equality: false, freeTextSearch: false })`.
+ */
+
+import type { AuthoringTypeNamespace } from '@prisma-next/framework-components/authoring';
+import {
+  CIPHERSTASH_STRING_CODEC_ID,
+  EQL_V2_ENCRYPTED_TYPE,
+} from '../extension-metadata/constants';
+
+export const cipherstashAuthoringTypes = {
+  cipherstash: {
+    EncryptedString: {
+      kind: 'typeConstructor',
+      args: [
+        {
+          kind: 'object',
+          name: 'options',
+          optional: true,
+          properties: {
+            equality: { kind: 'boolean', optional: true },
+            freeTextSearch: { kind: 'boolean', optional: true },
+          },
+        },
+      ],
+      output: {
+        codecId: CIPHERSTASH_STRING_CODEC_ID,
+        nativeType: EQL_V2_ENCRYPTED_TYPE,
+        typeParams: {
+          equality: { kind: 'arg', index: 0, path: ['equality'], default: true },
+          freeTextSearch: {
+            kind: 'arg',
+            index: 0,
+            path: ['freeTextSearch'],
+            default: true,
+          },
+        },
+      },
+    },
+  },
+} as const satisfies AuthoringTypeNamespace;

package/src/contract/contract.d.ts

@@ -0,0 +1,149 @@
+// ⚠️  GENERATED FILE - DO NOT EDIT
+// This file is automatically generated by 'prisma-next contract emit'.
+// To regenerate, run: prisma-next contract emit
+import type { CodecTypes as PgTypes } from '@prisma-next/target-postgres/codec-types';
+import type { JsonValue } from '@prisma-next/target-postgres/codec-types';
+import type { Char } from '@prisma-next/target-postgres/codec-types';
+import type { Varchar } from '@prisma-next/target-postgres/codec-types';
+import type { Numeric } from '@prisma-next/target-postgres/codec-types';
+import type { Bit } from '@prisma-next/target-postgres/codec-types';
+import type { VarBit } from '@prisma-next/target-postgres/codec-types';
+import type { Timestamp } from '@prisma-next/target-postgres/codec-types';
+import type { Timestamptz } from '@prisma-next/target-postgres/codec-types';
+import type { Time } from '@prisma-next/target-postgres/codec-types';
+import type { Timetz } from '@prisma-next/target-postgres/codec-types';
+import type { Interval } from '@prisma-next/target-postgres/codec-types';
+import type { QueryOperationTypes as PgAdapterQueryOps } from '@prisma-next/adapter-postgres/operation-types';
+
+import type {
+  ContractWithTypeMaps,
+  TypeMaps as TypeMapsType,
+} from '@prisma-next/sql-contract/types';
+import type {
+  Contract as ContractType,
+  ExecutionHashBase,
+  ProfileHashBase,
+  StorageHashBase,
+} from '@prisma-next/contract/types';
+
+export type StorageHash =
+  StorageHashBase<'sha256:efa685171bebbb8f078f08d12be3578bb5d96b71669dccc6cc9e4be96af8cdb4'>;
+export type ExecutionHash = ExecutionHashBase<string>;
+export type ProfileHash =
+  ProfileHashBase<'sha256:1a8dbe044289f30a1de958fe800cc5a8378b285d2e126a8c44b58864bac2c18e'>;
+
+export type CodecTypes = PgTypes;
+export type OperationTypes = Record<string, never>;
+export type LaneCodecTypes = CodecTypes;
+export type QueryOperationTypes = PgAdapterQueryOps<CodecTypes>;
+type DefaultLiteralValue<CodecId extends string, _Encoded> = CodecId extends keyof CodecTypes
+  ? CodecTypes[CodecId]['output']
+  : _Encoded;
+
+export type FieldOutputTypes = {
+  readonly EqlV2Configuration: {
+    readonly id: CodecTypes['pg/text@1']['output'];
+    readonly state: CodecTypes['pg/text@1']['output'];
+    readonly data: CodecTypes['pg/jsonb@1']['output'];
+  };
+};
+export type FieldInputTypes = {
+  readonly EqlV2Configuration: {
+    readonly id: CodecTypes['pg/text@1']['input'];
+    readonly state: CodecTypes['pg/text@1']['input'];
+    readonly data: CodecTypes['pg/jsonb@1']['input'];
+  };
+};
+export type TypeMaps = TypeMapsType<
+  CodecTypes,
+  OperationTypes,
+  QueryOperationTypes,
+  FieldOutputTypes,
+  FieldInputTypes
+>;
+
+type ContractBase = ContractType<
+  {
+    readonly tables: {
+      readonly eql_v2_configuration: {
+        columns: {
+          readonly id: {
+            readonly nativeType: 'text';
+            readonly codecId: 'pg/text@1';
+            readonly nullable: false;
+          };
+          readonly state: {
+            readonly nativeType: 'text';
+            readonly codecId: 'pg/text@1';
+            readonly nullable: false;
+          };
+          readonly data: {
+            readonly nativeType: 'jsonb';
+            readonly codecId: 'pg/jsonb@1';
+            readonly nullable: false;
+          };
+        };
+        primaryKey: { readonly columns: readonly ['id'] };
+        uniques: readonly [];
+        indexes: readonly [];
+        foreignKeys: readonly [];
+      };
+    };
+    readonly types: Record<string, never>;
+    readonly storageHash: StorageHash;
+  },
+  {
+    readonly EqlV2Configuration: {
+      readonly fields: {
+        readonly id: {
+          readonly nullable: false;
+          readonly type: { readonly kind: 'scalar'; readonly codecId: 'pg/text@1' };
+        };
+        readonly state: {
+          readonly nullable: false;
+          readonly type: { readonly kind: 'scalar'; readonly codecId: 'pg/text@1' };
+        };
+        readonly data: {
+          readonly nullable: false;
+          readonly type: { readonly kind: 'scalar'; readonly codecId: 'pg/jsonb@1' };
+        };
+      };
+      readonly relations: Record<string, never>;
+      readonly storage: {
+        readonly table: 'eql_v2_configuration';
+        readonly fields: {
+          readonly id: { readonly column: 'id' };
+          readonly state: { readonly column: 'state' };
+          readonly data: { readonly column: 'data' };
+        };
+      };
+    };
+  }
+> & {
+  readonly target: 'postgres';
+  readonly targetFamily: 'sql';
+  readonly roots: { readonly eql_v2_configuration: 'EqlV2Configuration' };
+  readonly capabilities: {
+    readonly postgres: {
+      readonly jsonAgg: true;
+      readonly lateral: true;
+      readonly limit: true;
+      readonly orderBy: true;
+      readonly returning: true;
+    };
+    readonly sql: {
+      readonly defaultInInsert: true;
+      readonly enums: true;
+      readonly returning: true;
+    };
+  };
+  readonly extensionPacks: {};
+  readonly meta: {};
+
+  readonly profileHash: ProfileHash;
+};
+
+export type Contract = ContractWithTypeMaps<ContractBase, TypeMaps>;
+
+export type Tables = Contract['storage']['tables'];
+export type Models = Contract['models'];

package/src/contract/contract.json

@@ -0,0 +1,104 @@
+{
+  "schemaVersion": "1",
+  "targetFamily": "sql",
+  "target": "postgres",
+  "profileHash": "sha256:1a8dbe044289f30a1de958fe800cc5a8378b285d2e126a8c44b58864bac2c18e",
+  "roots": {
+    "eql_v2_configuration": "EqlV2Configuration"
+  },
+  "models": {
+    "EqlV2Configuration": {
+      "fields": {
+        "data": {
+          "nullable": false,
+          "type": {
+            "codecId": "pg/jsonb@1",
+            "kind": "scalar"
+          }
+        },
+        "id": {
+          "nullable": false,
+          "type": {
+            "codecId": "pg/text@1",
+            "kind": "scalar"
+          }
+        },
+        "state": {
+          "nullable": false,
+          "type": {
+            "codecId": "pg/text@1",
+            "kind": "scalar"
+          }
+        }
+      },
+      "relations": {},
+      "storage": {
+        "fields": {
+          "data": {
+            "column": "data"
+          },
+          "id": {
+            "column": "id"
+          },
+          "state": {
+            "column": "state"
+          }
+        },
+        "table": "eql_v2_configuration"
+      }
+    }
+  },
+  "storage": {
+    "storageHash": "sha256:efa685171bebbb8f078f08d12be3578bb5d96b71669dccc6cc9e4be96af8cdb4",
+    "tables": {
+      "eql_v2_configuration": {
+        "columns": {
+          "data": {
+            "codecId": "pg/jsonb@1",
+            "nativeType": "jsonb",
+            "nullable": false
+          },
+          "id": {
+            "codecId": "pg/text@1",
+            "nativeType": "text",
+            "nullable": false
+          },
+          "state": {
+            "codecId": "pg/text@1",
+            "nativeType": "text",
+            "nullable": false
+          }
+        },
+        "foreignKeys": [],
+        "indexes": [],
+        "primaryKey": {
+          "columns": [
+            "id"
+          ]
+        },
+        "uniques": []
+      }
+    }
+  },
+  "capabilities": {
+    "postgres": {
+      "jsonAgg": true,
+      "lateral": true,
+      "limit": true,
+      "orderBy": true,
+      "returning": true
+    },
+    "sql": {
+      "defaultInInsert": true,
+      "enums": true,
+      "returning": true
+    }
+  },
+  "extensionPacks": {},
+  "meta": {},
+  "_generated": {
+    "warning": "⚠️  GENERATED FILE - DO NOT EDIT",
+    "message": "This file is automatically generated by \"prisma-next contract emit\".",
+    "regenerate": "To regenerate, run: prisma-next contract emit"
+  }
+}

package/src/contract/contract.prisma

@@ -0,0 +1,46 @@
+// PSL contract source for the `extension-cipherstash` package.
+//
+// Authored against the on-disk-in-package convention. The same emit
+// pipeline application authors use is applied here:
+//
+//   `prisma-next contract emit` → `<package>/src/contract/contract.{json,d.ts}`
+//   `prisma-next migration plan` → `<package>/migrations/cipherstash/<dirName>/`
+//
+// The descriptor at `src/exports/control.ts` then wires the emitted JSON
+// artefacts via JSON-import declarations.
+//
+// ## IR coverage and explicit deferral
+//
+// CipherStash should declare four kinds of typed objects in its
+// contract IR: tables, enums, composite types, and domains. Of these,
+// today's `SqlStorage` IR (`@prisma-next/sql-contract/types`) only
+// models tables and parameterised type instances (a fit for things
+// like pgvector's `vector(N)`, but not yet codec-less composite types,
+// standalone enums, or domains).
+//
+// The contract therefore declares the only IR-representable object
+// today (the `eql_v2_configuration` table) using portable scalar
+// types (`String` / `Json`). The actual database state — the `eql_v2`
+// schema, the typed `eql_v2_configuration_state` enum, the
+// `eql_v2_encrypted` composite, the `eql_v2.bloom_filter` /
+// `hmac_256` / `blake3` domains, and the various `ore_*` composites —
+// is created by the `installEqlBundle` migration op (which carries
+// the vendored bundle SQL byte-for-byte; see
+// `./src/migration/eql-bundle.ts`). The structural
+// `cipherstash:create-*-v1` no-op ops register the invariantIds the
+// verifier needs so its `applied_invariants` gate passes.
+//
+// Once the IR vocabulary expands to first-class composite types,
+// standalone enums, and domains, those typed objects shift up into
+// `storage.types` and the structural ops gain real verification work
+// (precheck SQL probing `pg_type` / `information_schema`).
+//
+// @see docs/architecture docs/adrs/ADR 211 - Contract spaces.md
+
+model EqlV2Configuration {
+  id    String @id
+  state String
+  data  Json
+
+  @@map("eql_v2_configuration")
+}

package/src/execution/abort.ts

@@ -0,0 +1,143 @@
+/**
+ * Cipherstash-internal `RUNTIME.ABORTED` phase wrapping.
+ *
+ * The framework`s `runtimeAborted(phase)` (`@prisma-next/framework-
+ * components/runtime`) constructs the canonical `RUNTIME.ABORTED`
+ * envelope (`code === 'RUNTIME.ABORTED'`, `category === 'RUNTIME'`,
+ * `details.phase`, `cause`) but its `phase` parameter is typed as
+ * the framework`s closed `RuntimeAbortedPhase` union — `encode`,
+ * `decode`, `stream`, `beforeExecute`, `afterExecute`, `onRow`. Those
+ * tags describe phases of `runtime.execute()` itself (see ADR 207`s
+ * "Where the runtime observes abort" table); cipherstash`s async
+ * observation points sit one layer outside the framework runtime:
+ *
+ *   - `bulk-encrypt`  — the bulk-encrypt middleware`s SDK round-trip
+ *     inside `beforeExecute`. Conceptually a sub-phase of the
+ *     framework`s `beforeExecute`, but tag-wise distinct so callers
+ *     can attribute the abort to the cipherstash SDK call rather
+ *     than to a generic middleware step.
+ *   - `decrypt`       — the single-cell `EncryptedString#decrypt()`
+ *     SDK call, invoked by the application after the framework
+ *     returns the row. Not inside any framework phase.
+ *   - `decrypt-all`   — the `decryptAll` walker`s `bulkDecrypt` calls,
+ *     invoked by the application after the framework returns the
+ *     row set. Not inside any framework phase.
+ *
+ * Rather than widen the framework union (which would conflate
+ * extension-specific tags with the framework`s own attribution
+ * sites), this module reuses the framework`s `runtimeError(...)`
+ * envelope builder directly — the *envelope shape* (the
+ * `RuntimeErrorEnvelope` interface, the `code` slot, the `category`
+ * slot, the `details.phase` slot, the `cause` field) is unchanged;
+ * only the set of legal `phase` string values grows. ADR 027`s
+ * envelope contract is preserved bit-for-bit.
+ *
+ * The `raceCipherstashAbort` helper mirrors framework
+ * `raceAgainstAbort` so cipherstash`s SDK-call sites get the same
+ * "return promptly even when the SDK ignores the signal" behaviour
+ * (the cooperative-cancellation model from ADR 207). Identity-
+ * checked sentinel rejection distinguishes abort-source from a
+ * codec-thrown envelope, matching the framework`s pattern. We
+ * duplicate the logic (rather than passing a cast tag to the
+ * framework helper) to keep the cipherstash `phase` strings
+ * cipherstash-internal — no widening of the framework union.
+ */
+
+import type { RuntimeErrorEnvelope } from '@prisma-next/framework-components/runtime';
+import { RUNTIME_ABORTED, runtimeError } from '@prisma-next/framework-components/runtime';
+
+/** Discriminator placed in `details.phase` of cipherstash-issued aborts. */
+export type CipherstashAbortPhase = 'bulk-encrypt' | 'decrypt' | 'decrypt-all';
+
+/**
+ * Construct a `RUNTIME.ABORTED` envelope tagged with a cipherstash
+ * phase. Reuses the framework`s `runtimeError(RUNTIME_ABORTED, ...)`
+ * envelope builder so the structural shape (`code`, `category`,
+ * `severity`, `message`, `details.phase`, `cause`) matches everything
+ * else the framework emits. Only the `phase` string set is
+ * cipherstash-specific.
+ */
+export function cipherstashAborted(
+  phase: CipherstashAbortPhase,
+  cause?: unknown,
+): RuntimeErrorEnvelope {
+  const envelope = runtimeError(RUNTIME_ABORTED, `Operation aborted during ${phase}`, { phase });
+  return Object.assign(envelope, { cause });
+}
+
+/**
+ * Pre-check helper: throw a cipherstash-tagged `RUNTIME.ABORTED`
+ * envelope if the supplied signal is already aborted at the call
+ * site. Mirrors framework `checkAborted` (which is typed against the
+ * framework`s phase union) — used to short-circuit the bulk-encrypt
+ * middleware`s pre-flight, the single-cell `decrypt()` pre-flight,
+ * and the `decryptAll` walker`s pre-flight before any SDK round-trip
+ * is scheduled.
+ */
+export function checkCipherstashAborted(
+  signal: AbortSignal | undefined,
+  phase: CipherstashAbortPhase,
+): void {
+  if (signal?.aborted) {
+    throw cipherstashAborted(phase, signal.reason);
+  }
+}
+
+/**
+ * Race a cipherstash SDK promise against the supplied `AbortSignal`
+ * so the awaiting caller is rejected promptly with a
+ * `RUNTIME.ABORTED` envelope as soon as the signal aborts — even
+ * when the SDK body itself ignores the signal. Cooperative
+ * cancellation: in-flight SDK calls that ignore the signal continue
+ * running in the background and complete; the abort-attributed
+ * rejection is what the cipherstash caller sees (the SDK`s eventual
+ * resolution is silently abandoned per ADR 207`s "cooperative
+ * cancellation, not termination" contract).
+ *
+ * Mirrors framework `raceAgainstAbort` line-for-line aside from the
+ * cipherstash-typed phase parameter and the cipherstash-tagged
+ * envelope construction. The sentinel-identity attribution is
+ * load-bearing for the same reason ADR 207 spells out: a codec /
+ * SDK that itself throws a `RUNTIME.ENCODE_FAILED` /
+ * `RUNTIME.DECODE_FAILED` (or any other named envelope) must pass
+ * through unchanged — only the cipherstash-installed listener ever
+ * rejects with the local sentinel reference, so an `error ===
+ * sentinel` identity check after the race is unambiguous.
+ */
+export async function raceCipherstashAbort<T>(
+  work: Promise<T>,
+  signal: AbortSignal | undefined,
+  phase: CipherstashAbortPhase,
+): Promise<T> {
+  if (signal === undefined) {
+    return await work;
+  }
+  const sentinel: { reason: unknown } = { reason: undefined };
+  let onAbort: (() => void) | undefined;
+
+  const abortPromise = new Promise<never>((_, reject) => {
+    if (signal.aborted) {
+      sentinel.reason = signal.reason;
+      reject(sentinel);
+      return;
+    }
+    onAbort = () => {
+      sentinel.reason = signal.reason;
+      reject(sentinel);
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+
+  try {
+    return await Promise.race([work, abortPromise]);
+  } catch (error) {
+    if (error === sentinel) {
+      throw cipherstashAborted(phase, sentinel.reason);
+    }
+    throw error;
+  } finally {
+    if (onAbort) {
+      signal.removeEventListener('abort', onAbort);
+    }
+  }
+}