@noy-db/hub 0.2.0-pre.2 → 0.2.0-pre.21

package/dist/sealed-record/index.d.cts

@@ -0,0 +1,123 @@
+export { q as SealedRecordExpiredError, r as SealedRecordMismatchError } from '../errors-Dkc_fi-S.cjs';
+
+/**
+ * Wire + binding types for record-scoped CEK sealing (#306 slices 2-3).
+ *
+ * A vault owner who holds the collection DEK can **seal a single record's
+ * content-encryption key (CEK)** to an `at-*` host (e.g. a KMS-backed
+ * {@link RecipientSealer}) so that host — and only that host — can decrypt
+ * exactly that one record, with no access to the vault DEK and no ability to
+ * read any other record. This is the record-granular counterpart to the
+ * bundle-granular sealed-credential delivery (`SealedEnvelope`).
+ *
+ * Two shapes live here:
+ *
+ *  - {@link SealedCekDeliveryEnvelope} — the **thin delivery envelope** the
+ *    grantor writes to `_sealed_cek/<collection>/<id>/<pid>`. It carries only
+ *    routing metadata (`pid`, `expiresAt`) in the clear plus the opaque sealed
+ *    `payload`. The `expiresAt` here is a *fast-path* hint; the authoritative
+ *    expiry lives INSIDE the sealed payload (see below).
+ *
+ *  - {@link SealedCekBinding} — the plaintext struct that is sealed for the
+ *    host. It binds the CEK to its `{collection, id}` and an authoritative
+ *    `expiresAt`, so a host cannot take a CEK sealed for record A and apply it
+ *    to record B's envelope (mismatch is rejected), nor read past expiry. The
+ *    binding is the security boundary; the delivery envelope is just transport.
+ *
+ * @module
+ */
+/**
+ * Thin delivery envelope persisted at
+ * `_sealed_cek/<collection>/<id>/<pid>`. The grantor writes one per
+ * (record, recipient host) pair. `payload` is the base64 of the bytes returned
+ * by {@link RecipientSealer.sealForRecipient} over a UTF-8
+ * `JSON.stringify({@link SealedCekBinding})`.
+ *
+ * `expiresAt` is duplicated here for a cheap pre-unseal reject, but is NOT
+ * authoritative — the binding inside `payload` carries the expiry the host
+ * verifies after unsealing, so a tampered delivery envelope cannot extend a
+ * grant.
+ */
+interface SealedCekDeliveryEnvelope {
+    /** Envelope schema version. */
+    readonly v: 1;
+    /** Magic marker for forensics + format detection. */
+    readonly _noydb_sealed_cek: 1;
+    /** Recipient host provider id; matches the sealer's `.id` / hint `pid`. */
+    readonly pid: string;
+    /** base64 of the sealed {@link SealedCekBinding} bytes. */
+    readonly payload: string;
+    /** Fast-path expiry hint (ISO 8601). Authoritative copy is inside `payload`. */
+    readonly expiresAt: string;
+}
+/**
+ * The plaintext struct sealed for the recipient host. After the host unseals
+ * `SealedCekDeliveryEnvelope.payload` it parses this and MUST verify:
+ *  - `collection` + `id` match the record envelope it is decrypting, and
+ *  - `expiresAt` has not passed (authoritative expiry check).
+ *
+ * `cek` is the base64 of the raw 32-byte AES-256-GCM record CEK.
+ */
+interface SealedCekBinding {
+    /** Collection the CEK belongs to. */
+    readonly collection: string;
+    /** Record id the CEK belongs to. */
+    readonly id: string;
+    /** base64 of the raw AES-256-GCM CEK bytes. */
+    readonly cek: string;
+    /** Authoritative expiry (ISO 8601). */
+    readonly expiresAt: string;
+}
+
+/**
+ * `@noy-db/hub/sealed-record` — host-side opener for record-scoped CEK
+ * sealing (#306 slices 2-3).
+ *
+ * The **grantor** side (sealing a record's CEK to a host, revoking, and hard
+ * rotation) lives on `Vault` (`vault.sealRecordToHost` /
+ * `vault.revokeSealedRecord` / `vault.rotateRecordCek`) because it needs the
+ * collection DEK. This subpath exposes the **recipient host** side:
+ * {@link openSealedRecord} reconstructs a single record's plaintext from
+ * (a) the sealed-CEK delivery envelope, (b) the record's encrypted envelope
+ * body, and (c) the host's own unsealer — and **nothing else**. The host never
+ * touches a vault DEK and can decrypt exactly the one bound record.
+ *
+ * @module
+ */
+
+/**
+ * Host-side: decrypt a single record whose CEK was sealed to this host by a
+ * vault grantor via `vault.sealRecordToHost()`.
+ *
+ * Verification order (security-critical — do NOT reorder past the unseal):
+ *  1. **Fast-path expiry** — reject on the delivery envelope's clear-text
+ *     `expiresAt` before doing any (potentially expensive) unseal work. This is
+ *     a hint only.
+ *  2. **Unseal** the `payload` with the host's `recipientSealer.unseal` →
+ *     parse the {@link SealedCekBinding}.
+ *  3. **Binding match** — the binding's `{collection, id}` MUST equal the
+ *     expected pair, else {@link SealedRecordMismatchError}. This is the
+ *     host-denial boundary (a CEK sealed for record A cannot open record B).
+ *  4. **Authoritative expiry** — re-check `binding.expiresAt` (the copy that
+ *     cannot be forged by editing the delivery envelope), else
+ *     {@link SealedRecordExpiredError}.
+ *  5. **Decrypt** the record body under the unsealed CEK. A CEK from a
+ *     PRE-rotation seal applied to a POST-rotation live envelope passes (1)-(4)
+ *     but fails the AES-GCM auth tag → `TamperedError` from `decrypt`.
+ *
+ * @param sealedCekEnvelope The `SealedCekDeliveryEnvelope` written by the grantor.
+ * @param recordEnvelope    The record's `{ _iv, _data }` (the encrypted body).
+ * @param recipientSealer   The host's unsealer (`{ unseal(bytes) }`) — e.g. a
+ *                          KMS-backed sealer or `MemoryRecipientSealer`.
+ * @param expectedCollection Collection the caller believes `recordEnvelope` is in.
+ * @param expectedId         Record id the caller believes `recordEnvelope` is.
+ * @returns The decrypted record body as a JSON string.
+ */
+declare function openSealedRecord(sealedCekEnvelope: SealedCekDeliveryEnvelope, recordEnvelope: {
+    readonly _iv: string;
+    readonly _data: string;
+}, recipientSealer: {
+    unseal(bytes: Uint8Array): Promise<Uint8Array>;
+}, expectedCollection: string, expectedId: string): Promise<string>;
+
+export { type SealedCekBinding, type SealedCekDeliveryEnvelope, openSealedRecord };

package/dist/sealed-record/index.d.ts

@@ -0,0 +1,123 @@
+export { q as SealedRecordExpiredError, r as SealedRecordMismatchError } from '../errors-Dkc_fi-S.js';
+
+/**
+ * Wire + binding types for record-scoped CEK sealing (#306 slices 2-3).
+ *
+ * A vault owner who holds the collection DEK can **seal a single record's
+ * content-encryption key (CEK)** to an `at-*` host (e.g. a KMS-backed
+ * {@link RecipientSealer}) so that host — and only that host — can decrypt
+ * exactly that one record, with no access to the vault DEK and no ability to
+ * read any other record. This is the record-granular counterpart to the
+ * bundle-granular sealed-credential delivery (`SealedEnvelope`).
+ *
+ * Two shapes live here:
+ *
+ *  - {@link SealedCekDeliveryEnvelope} — the **thin delivery envelope** the
+ *    grantor writes to `_sealed_cek/<collection>/<id>/<pid>`. It carries only
+ *    routing metadata (`pid`, `expiresAt`) in the clear plus the opaque sealed
+ *    `payload`. The `expiresAt` here is a *fast-path* hint; the authoritative
+ *    expiry lives INSIDE the sealed payload (see below).
+ *
+ *  - {@link SealedCekBinding} — the plaintext struct that is sealed for the
+ *    host. It binds the CEK to its `{collection, id}` and an authoritative
+ *    `expiresAt`, so a host cannot take a CEK sealed for record A and apply it
+ *    to record B's envelope (mismatch is rejected), nor read past expiry. The
+ *    binding is the security boundary; the delivery envelope is just transport.
+ *
+ * @module
+ */
+/**
+ * Thin delivery envelope persisted at
+ * `_sealed_cek/<collection>/<id>/<pid>`. The grantor writes one per
+ * (record, recipient host) pair. `payload` is the base64 of the bytes returned
+ * by {@link RecipientSealer.sealForRecipient} over a UTF-8
+ * `JSON.stringify({@link SealedCekBinding})`.
+ *
+ * `expiresAt` is duplicated here for a cheap pre-unseal reject, but is NOT
+ * authoritative — the binding inside `payload` carries the expiry the host
+ * verifies after unsealing, so a tampered delivery envelope cannot extend a
+ * grant.
+ */
+interface SealedCekDeliveryEnvelope {
+    /** Envelope schema version. */
+    readonly v: 1;
+    /** Magic marker for forensics + format detection. */
+    readonly _noydb_sealed_cek: 1;
+    /** Recipient host provider id; matches the sealer's `.id` / hint `pid`. */
+    readonly pid: string;
+    /** base64 of the sealed {@link SealedCekBinding} bytes. */
+    readonly payload: string;
+    /** Fast-path expiry hint (ISO 8601). Authoritative copy is inside `payload`. */
+    readonly expiresAt: string;
+}
+/**
+ * The plaintext struct sealed for the recipient host. After the host unseals
+ * `SealedCekDeliveryEnvelope.payload` it parses this and MUST verify:
+ *  - `collection` + `id` match the record envelope it is decrypting, and
+ *  - `expiresAt` has not passed (authoritative expiry check).
+ *
+ * `cek` is the base64 of the raw 32-byte AES-256-GCM record CEK.
+ */
+interface SealedCekBinding {
+    /** Collection the CEK belongs to. */
+    readonly collection: string;
+    /** Record id the CEK belongs to. */
+    readonly id: string;
+    /** base64 of the raw AES-256-GCM CEK bytes. */
+    readonly cek: string;
+    /** Authoritative expiry (ISO 8601). */
+    readonly expiresAt: string;
+}
+
+/**
+ * `@noy-db/hub/sealed-record` — host-side opener for record-scoped CEK
+ * sealing (#306 slices 2-3).
+ *
+ * The **grantor** side (sealing a record's CEK to a host, revoking, and hard
+ * rotation) lives on `Vault` (`vault.sealRecordToHost` /
+ * `vault.revokeSealedRecord` / `vault.rotateRecordCek`) because it needs the
+ * collection DEK. This subpath exposes the **recipient host** side:
+ * {@link openSealedRecord} reconstructs a single record's plaintext from
+ * (a) the sealed-CEK delivery envelope, (b) the record's encrypted envelope
+ * body, and (c) the host's own unsealer — and **nothing else**. The host never
+ * touches a vault DEK and can decrypt exactly the one bound record.
+ *
+ * @module
+ */
+
+/**
+ * Host-side: decrypt a single record whose CEK was sealed to this host by a
+ * vault grantor via `vault.sealRecordToHost()`.
+ *
+ * Verification order (security-critical — do NOT reorder past the unseal):
+ *  1. **Fast-path expiry** — reject on the delivery envelope's clear-text
+ *     `expiresAt` before doing any (potentially expensive) unseal work. This is
+ *     a hint only.
+ *  2. **Unseal** the `payload` with the host's `recipientSealer.unseal` →
+ *     parse the {@link SealedCekBinding}.
+ *  3. **Binding match** — the binding's `{collection, id}` MUST equal the
+ *     expected pair, else {@link SealedRecordMismatchError}. This is the
+ *     host-denial boundary (a CEK sealed for record A cannot open record B).
+ *  4. **Authoritative expiry** — re-check `binding.expiresAt` (the copy that
+ *     cannot be forged by editing the delivery envelope), else
+ *     {@link SealedRecordExpiredError}.
+ *  5. **Decrypt** the record body under the unsealed CEK. A CEK from a
+ *     PRE-rotation seal applied to a POST-rotation live envelope passes (1)-(4)
+ *     but fails the AES-GCM auth tag → `TamperedError` from `decrypt`.
+ *
+ * @param sealedCekEnvelope The `SealedCekDeliveryEnvelope` written by the grantor.
+ * @param recordEnvelope    The record's `{ _iv, _data }` (the encrypted body).
+ * @param recipientSealer   The host's unsealer (`{ unseal(bytes) }`) — e.g. a
+ *                          KMS-backed sealer or `MemoryRecipientSealer`.
+ * @param expectedCollection Collection the caller believes `recordEnvelope` is in.
+ * @param expectedId         Record id the caller believes `recordEnvelope` is.
+ * @returns The decrypted record body as a JSON string.
+ */
+declare function openSealedRecord(sealedCekEnvelope: SealedCekDeliveryEnvelope, recordEnvelope: {
+    readonly _iv: string;
+    readonly _data: string;
+}, recipientSealer: {
+    unseal(bytes: Uint8Array): Promise<Uint8Array>;
+}, expectedCollection: string, expectedId: string): Promise<string>;
+
+export { type SealedCekBinding, type SealedCekDeliveryEnvelope, openSealedRecord };

package/dist/sealed-record/index.js

@@ -0,0 +1,42 @@
+import {
+  base64ToBuffer,
+  decrypt
+} from "../chunk-37VGJM3T.js";
+import {
+  SealedRecordExpiredError,
+  SealedRecordMismatchError
+} from "../chunk-OTWT6BAJ.js";
+
+// src/sealed-record/index.ts
+var subtle = globalThis.crypto.subtle;
+async function openSealedRecord(sealedCekEnvelope, recordEnvelope, recipientSealer, expectedCollection, expectedId) {
+  if (Date.parse(sealedCekEnvelope.expiresAt) <= Date.now()) {
+    throw new SealedRecordExpiredError(sealedCekEnvelope.expiresAt);
+  }
+  const payloadBytes = base64ToBuffer(sealedCekEnvelope.payload);
+  const openedBytes = await recipientSealer.unseal(payloadBytes);
+  const binding = JSON.parse(new TextDecoder().decode(openedBytes));
+  if (binding.collection !== expectedCollection || binding.id !== expectedId) {
+    throw new SealedRecordMismatchError(
+      { collection: expectedCollection, id: expectedId },
+      { collection: binding.collection, id: binding.id }
+    );
+  }
+  if (Date.parse(binding.expiresAt) <= Date.now()) {
+    throw new SealedRecordExpiredError(binding.expiresAt);
+  }
+  const cek = await subtle.importKey(
+    "raw",
+    base64ToBuffer(binding.cek),
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["decrypt"]
+  );
+  return decrypt(recordEnvelope._iv, recordEnvelope._data, cek);
+}
+export {
+  SealedRecordExpiredError,
+  SealedRecordMismatchError,
+  openSealedRecord
+};
+//# sourceMappingURL=index.js.map

package/dist/sealed-record/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sealed-record/index.ts"],"sourcesContent":["/**\n * `@noy-db/hub/sealed-record` — host-side opener for record-scoped CEK\n * sealing (#306 slices 2-3).\n *\n * The **grantor** side (sealing a record's CEK to a host, revoking, and hard\n * rotation) lives on `Vault` (`vault.sealRecordToHost` /\n * `vault.revokeSealedRecord` / `vault.rotateRecordCek`) because it needs the\n * collection DEK. This subpath exposes the **recipient host** side:\n * {@link openSealedRecord} reconstructs a single record's plaintext from\n * (a) the sealed-CEK delivery envelope, (b) the record's encrypted envelope\n * body, and (c) the host's own unsealer — and **nothing else**. The host never\n * touches a vault DEK and can decrypt exactly the one bound record.\n *\n * @module\n */\n\nimport { decrypt, base64ToBuffer } from '../crypto.js'\nimport {\n  SealedRecordExpiredError,\n  SealedRecordMismatchError,\n} from '../errors.js'\nimport type {\n  SealedCekDeliveryEnvelope,\n  SealedCekBinding,\n} from './types.js'\n\nexport type { SealedCekDeliveryEnvelope, SealedCekBinding } from './types.js'\nexport { SealedRecordExpiredError, SealedRecordMismatchError } from '../errors.js'\n\nconst subtle = globalThis.crypto.subtle\n\n/**\n * Host-side: decrypt a single record whose CEK was sealed to this host by a\n * vault grantor via `vault.sealRecordToHost()`.\n *\n * Verification order (security-critical — do NOT reorder past the unseal):\n *  1. **Fast-path expiry** — reject on the delivery envelope's clear-text\n *     `expiresAt` before doing any (potentially expensive) unseal work. This is\n *     a hint only.\n *  2. **Unseal** the `payload` with the host's `recipientSealer.unseal` →\n *     parse the {@link SealedCekBinding}.\n *  3. **Binding match** — the binding's `{collection, id}` MUST equal the\n *     expected pair, else {@link SealedRecordMismatchError}. This is the\n *     host-denial boundary (a CEK sealed for record A cannot open record B).\n *  4. **Authoritative expiry** — re-check `binding.expiresAt` (the copy that\n *     cannot be forged by editing the delivery envelope), else\n *     {@link SealedRecordExpiredError}.\n *  5. **Decrypt** the record body under the unsealed CEK. A CEK from a\n *     PRE-rotation seal applied to a POST-rotation live envelope passes (1)-(4)\n *     but fails the AES-GCM auth tag → `TamperedError` from `decrypt`.\n *\n * @param sealedCekEnvelope The `SealedCekDeliveryEnvelope` written by the grantor.\n * @param recordEnvelope    The record's `{ _iv, _data }` (the encrypted body).\n * @param recipientSealer   The host's unsealer (`{ unseal(bytes) }`) — e.g. a\n *                          KMS-backed sealer or `MemoryRecipientSealer`.\n * @param expectedCollection Collection the caller believes `recordEnvelope` is in.\n * @param expectedId         Record id the caller believes `recordEnvelope` is.\n * @returns The decrypted record body as a JSON string.\n */\nexport async function openSealedRecord(\n  sealedCekEnvelope: SealedCekDeliveryEnvelope,\n  recordEnvelope: { readonly _iv: string; readonly _data: string },\n  recipientSealer: { unseal(bytes: Uint8Array): Promise<Uint8Array> },\n  expectedCollection: string,\n  expectedId: string,\n): Promise<string> {\n  // (1) Fast-path expiry on the (unauthenticated) delivery envelope.\n  if (Date.parse(sealedCekEnvelope.expiresAt) <= Date.now()) {\n    throw new SealedRecordExpiredError(sealedCekEnvelope.expiresAt)\n  }\n\n  // (2) Unseal → parse binding.\n  const payloadBytes = base64ToBuffer(sealedCekEnvelope.payload)\n  const openedBytes = await recipientSealer.unseal(payloadBytes)\n  const binding = JSON.parse(new TextDecoder().decode(openedBytes)) as SealedCekBinding\n\n  // (3) Binding match — host-denial boundary.\n  if (binding.collection !== expectedCollection || binding.id !== expectedId) {\n    throw new SealedRecordMismatchError(\n      { collection: expectedCollection, id: expectedId },\n      { collection: binding.collection, id: binding.id },\n    )\n  }\n\n  // (4) Authoritative expiry — the copy that cannot be forged on the envelope.\n  if (Date.parse(binding.expiresAt) <= Date.now()) {\n    throw new SealedRecordExpiredError(binding.expiresAt)\n  }\n\n  // (5) Import the raw CEK + decrypt the body. Wrong-key (pre-rotation CEK vs\n  // post-rotation body) surfaces as TamperedError from decrypt's GCM tag check.\n  const cek = await subtle.importKey(\n    'raw',\n    base64ToBuffer(binding.cek) as BufferSource,\n    { name: 'AES-GCM', length: 256 },\n    false,\n    ['decrypt'],\n  )\n  return decrypt(recordEnvelope._iv, recordEnvelope._data, cek)\n}\n"],"mappings":";;;;;;;;;;AA6BA,IAAM,SAAS,WAAW,OAAO;AA8BjC,eAAsB,iBACpB,mBACA,gBACA,iBACA,oBACA,YACiB;AAEjB,MAAI,KAAK,MAAM,kBAAkB,SAAS,KAAK,KAAK,IAAI,GAAG;AACzD,UAAM,IAAI,yBAAyB,kBAAkB,SAAS;AAAA,EAChE;AAGA,QAAM,eAAe,eAAe,kBAAkB,OAAO;AAC7D,QAAM,cAAc,MAAM,gBAAgB,OAAO,YAAY;AAC7D,QAAM,UAAU,KAAK,MAAM,IAAI,YAAY,EAAE,OAAO,WAAW,CAAC;AAGhE,MAAI,QAAQ,eAAe,sBAAsB,QAAQ,OAAO,YAAY;AAC1E,UAAM,IAAI;AAAA,MACR,EAAE,YAAY,oBAAoB,IAAI,WAAW;AAAA,MACjD,EAAE,YAAY,QAAQ,YAAY,IAAI,QAAQ,GAAG;AAAA,IACnD;AAAA,EACF;AAGA,MAAI,KAAK,MAAM,QAAQ,SAAS,KAAK,KAAK,IAAI,GAAG;AAC/C,UAAM,IAAI,yBAAyB,QAAQ,SAAS;AAAA,EACtD;AAIA,QAAM,MAAM,MAAM,OAAO;AAAA,IACvB;AAAA,IACA,eAAe,QAAQ,GAAG;AAAA,IAC1B,EAAE,MAAM,WAAW,QAAQ,IAAI;AAAA,IAC/B;AAAA,IACA,CAAC,SAAS;AAAA,EACZ;AACA,SAAO,QAAQ,eAAe,KAAK,eAAe,OAAO,GAAG;AAC9D;","names":[]}