@syncular/core 0.63.0 → 0.64.0

package/dist/crypto.d.ts

@@ -10,14 +10,25 @@ export declare const NONCE_LENGTH = 12;
 export declare const KEY_LENGTH = 32;
 /**
  * Client-local decrypt failure (SPEC.md §5.11, §10.3). Never on the wire —
- * the `client.` family is client-only. Raised at the apply seam for an
- * unknown envelope version, unknown `keyId`, GCM auth failure (wrong key), a
- * malformed envelope, or a post-decrypt value-parse failure. Not retryable.
+ * the `client.` family is client-only. Raised at the apply seam. A `keyId`
+ * the keyring does not hold is `client.encryption_key_missing` with
+ * `details` naming the key id (and the table at the apply seam); an unknown
+ * envelope version, GCM auth failure (wrong key), a malformed envelope, or a
+ * post-decrypt value-parse failure is `client.decrypt_failed`. Not
+ * retryable.
  */
 export declare class DecryptError extends Error {
     readonly name = "DecryptError";
-    readonly code = "client.decrypt_failed";
+    readonly code: 'client.decrypt_failed' | 'client.encryption_key_missing';
     readonly retryable = false;
+    readonly details: {
+        readonly table?: string | undefined;
+        readonly keyId: string;
+    } | undefined;
+    constructor(message: string, missingKey?: {
+        readonly table?: string | undefined;
+        readonly keyId: string;
+    });
 }
 /**
  * Client-local encrypt failure (SPEC.md §5.11, §10.3). Never on the wire.
@@ -65,7 +76,9 @@ export declare function decodeEnvelope(bytes: Uint8Array): Envelope;
 export declare function encryptValue(declaredType: DeclaredType, value: PlainValue, keyId: string, key: Uint8Array, nonceSource?: NonceSource): Promise<Uint8Array>;
 /**
  * Decrypt a §5.11 envelope back to a declared-type value. `keyProvider`
- * resolves the envelope's `keyId` to key bytes; a missing key or GCM tag
- * mismatch is {@link DecryptError} (`client.decrypt_failed`).
+ * resolves the envelope's `keyId` to key bytes. A missing key is a
+ * {@link DecryptError} coded `client.encryption_key_missing` whose details
+ * name the key id and, when given, `table`; a GCM tag mismatch is
+ * `client.decrypt_failed`.
  */
-export declare function decryptValue(declaredType: DeclaredType, envelopeBytes: Uint8Array, keyProvider: (keyId: string) => Uint8Array | undefined): Promise<PlainValue>;
+export declare function decryptValue(declaredType: DeclaredType, envelopeBytes: Uint8Array, keyProvider: (keyId: string) => Uint8Array | undefined, table?: string): Promise<PlainValue>;

package/dist/crypto.js

@@ -22,14 +22,25 @@ export const NONCE_LENGTH = 12;
 export const KEY_LENGTH = 32;
 /**
  * Client-local decrypt failure (SPEC.md §5.11, §10.3). Never on the wire —
- * the `client.` family is client-only. Raised at the apply seam for an
- * unknown envelope version, unknown `keyId`, GCM auth failure (wrong key), a
- * malformed envelope, or a post-decrypt value-parse failure. Not retryable.
+ * the `client.` family is client-only. Raised at the apply seam. A `keyId`
+ * the keyring does not hold is `client.encryption_key_missing` with
+ * `details` naming the key id (and the table at the apply seam); an unknown
+ * envelope version, GCM auth failure (wrong key), a malformed envelope, or a
+ * post-decrypt value-parse failure is `client.decrypt_failed`. Not
+ * retryable.
  */
 export class DecryptError extends Error {
     name = 'DecryptError';
-    code = 'client.decrypt_failed';
+    code;
     retryable = false;
+    details;
+    constructor(message, missingKey) {
+        super(message);
+        this.code = missingKey
+            ? 'client.encryption_key_missing'
+            : 'client.decrypt_failed';
+        this.details = missingKey;
+    }
 }
 /**
  * Client-local encrypt failure (SPEC.md §5.11, §10.3). Never on the wire.
@@ -240,14 +251,19 @@ export async function encryptValue(declaredType, value, keyId, key, nonceSource
 }
 /**
  * Decrypt a §5.11 envelope back to a declared-type value. `keyProvider`
- * resolves the envelope's `keyId` to key bytes; a missing key or GCM tag
- * mismatch is {@link DecryptError} (`client.decrypt_failed`).
+ * resolves the envelope's `keyId` to key bytes. A missing key is a
+ * {@link DecryptError} coded `client.encryption_key_missing` whose details
+ * name the key id and, when given, `table`; a GCM tag mismatch is
+ * `client.decrypt_failed`.
  */
-export async function decryptValue(declaredType, envelopeBytes, keyProvider) {
+export async function decryptValue(declaredType, envelopeBytes, keyProvider, table) {
     const envelope = decodeEnvelope(envelopeBytes);
     const key = keyProvider(envelope.keyId);
     if (key === undefined) {
-        throw new DecryptError(`no key for keyId ${JSON.stringify(envelope.keyId)}`);
+        throw new DecryptError('no key for the envelope keyId', {
+            table,
+            keyId: envelope.keyId,
+        });
     }
     const cryptoKey = await importAesKey(key);
     let plaintext;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/core",
-  "version": "0.63.0",
+  "version": "0.64.0",
   "description": "Core protocol types and shared utilities for the Syncular sync framework",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",

package/src/crypto.ts

@@ -39,14 +39,34 @@ export const KEY_LENGTH = 32;
 
 /**
  * Client-local decrypt failure (SPEC.md §5.11, §10.3). Never on the wire —
- * the `client.` family is client-only. Raised at the apply seam for an
- * unknown envelope version, unknown `keyId`, GCM auth failure (wrong key), a
- * malformed envelope, or a post-decrypt value-parse failure. Not retryable.
+ * the `client.` family is client-only. Raised at the apply seam. A `keyId`
+ * the keyring does not hold is `client.encryption_key_missing` with
+ * `details` naming the key id (and the table at the apply seam); an unknown
+ * envelope version, GCM auth failure (wrong key), a malformed envelope, or a
+ * post-decrypt value-parse failure is `client.decrypt_failed`. Not
+ * retryable.
  */
 export class DecryptError extends Error {
   override readonly name = 'DecryptError';
-  readonly code = 'client.decrypt_failed';
+  readonly code: 'client.decrypt_failed' | 'client.encryption_key_missing';
   readonly retryable = false;
+  readonly details:
+    | { readonly table?: string | undefined; readonly keyId: string }
+    | undefined;
+
+  constructor(
+    message: string,
+    missingKey?: {
+      readonly table?: string | undefined;
+      readonly keyId: string;
+    },
+  ) {
+    super(message);
+    this.code = missingKey
+      ? 'client.encryption_key_missing'
+      : 'client.decrypt_failed';
+    this.details = missingKey;
+  }
 }
 
 /**
@@ -313,20 +333,24 @@ export async function encryptValue(
 
 /**
  * Decrypt a §5.11 envelope back to a declared-type value. `keyProvider`
- * resolves the envelope's `keyId` to key bytes; a missing key or GCM tag
- * mismatch is {@link DecryptError} (`client.decrypt_failed`).
+ * resolves the envelope's `keyId` to key bytes. A missing key is a
+ * {@link DecryptError} coded `client.encryption_key_missing` whose details
+ * name the key id and, when given, `table`; a GCM tag mismatch is
+ * `client.decrypt_failed`.
  */
 export async function decryptValue(
   declaredType: DeclaredType,
   envelopeBytes: Uint8Array,
   keyProvider: (keyId: string) => Uint8Array | undefined,
+  table?: string,
 ): Promise<PlainValue> {
   const envelope = decodeEnvelope(envelopeBytes);
   const key = keyProvider(envelope.keyId);
   if (key === undefined) {
-    throw new DecryptError(
-      `no key for keyId ${JSON.stringify(envelope.keyId)}`,
-    );
+    throw new DecryptError('no key for the envelope keyId', {
+      table,
+      keyId: envelope.keyId,
+    });
   }
   const cryptoKey = await importAesKey(key);
   let plaintext: Uint8Array;