@coffre/core 0.1.6 → 0.1.7

package/dist/kek.d.ts

@@ -69,4 +69,20 @@ export declare class AwsKmsKekProvider implements KekProvider {
   unwrap(wrapped: WrappedDek, ctx: SecretContext, operation?: KeyOperation): Promise<Buffer>;
 }
 //#endregion
+//#region src/kek/check.d.ts
+/** The action of the vault's entry that holds a vault key's check. */
+export declare const KEY_CHECK = "key.check";
+/** The known value a check wraps: the size of a data key. */
+export declare const KEY_CHECK_VALUE: Buffer;
+/** The context a check is wrapped in, which no secret has: the nil UUID throughout. */
+export declare const KEY_CHECK_CONTEXT: SecretContext;
+/**
+ * Whether `key`, a local vault key, is the one that wrapped `check`: it
+ * opens it, under the vault ID the check names, to the known value. The ID
+ * is bound into the wrap, so a match also says the ID is the escrowed one's.
+ */
+export declare function opensKeyCheck(key: Buffer, check: WrappedDek): Promise<boolean>;
+/** The id the log records for entries the app signs with `key`, its APP_KEY. */
+export declare function appLogKeyId(key: Uint8Array): string;
+//#endregion
 export { type AwsCredentials, type AwsKmsOptions, DEK_BYTES, KekBadClaimError, KekCancelledError, type KekProvider, KekRegistry, KekUnavailableError, type KeyOperation, type WrappedDek };

package/dist/kek.js

@@ -1,3 +1,4 @@
+import { deriveLogKey } from "./audit.js";
 import { i as KekUnavailableError, n as KekBadClaimError, o as checkContext, r as KekCancelledError, s as encodeAad, t as DEK_BYTES } from "./types-Mi7-Tzj9.js";
 import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 //#region src/kek/cancellation.ts
@@ -483,4 +484,38 @@ var Slots = class {
 	}
 };
 //#endregion
-export { AwsKmsKekProvider, DEK_BYTES, KekBadClaimError, KekCancelledError, KekRegistry, KekUnavailableError, LocalKekProvider, awsKms, equalBytes };
+//#region src/kek/check.ts
+/** The action of the vault's entry that holds a vault key's check. */
+const KEY_CHECK = "key.check";
+/** The known value a check wraps: the size of a data key. */
+const KEY_CHECK_VALUE = createHash("sha256").update("coffre.kek.check.v1").digest();
+const NIL = "00000000-0000-0000-0000-000000000000";
+/** The context a check is wrapped in, which no secret has: the nil UUID throughout. */
+const KEY_CHECK_CONTEXT = {
+	projectId: NIL,
+	environmentId: NIL,
+	secretId: NIL
+};
+/**
+* Whether `key`, a local vault key, is the one that wrapped `check`: it
+* opens it, under the vault ID the check names, to the known value. The ID
+* is bound into the wrap, so a match also says the ID is the escrowed one's.
+*/
+async function opensKeyCheck(key, check) {
+	if (check.kekProvider !== "local" || key.length !== 32) return false;
+	try {
+		const value = await new LocalKekProvider(key, check.kekId, check.kekVersion).unwrap(check, KEY_CHECK_CONTEXT);
+		const right = equalBytes(value, KEY_CHECK_VALUE);
+		value.fill(0);
+		return right;
+	} catch (error) {
+		if (error instanceof KekBadClaimError) return false;
+		throw error;
+	}
+}
+/** The id the log records for entries the app signs with `key`, its APP_KEY. */
+function appLogKeyId(key) {
+	return deriveLogKey("app", key).keyId;
+}
+//#endregion
+export { AwsKmsKekProvider, DEK_BYTES, KEY_CHECK, KEY_CHECK_CONTEXT, KEY_CHECK_VALUE, KekBadClaimError, KekCancelledError, KekRegistry, KekUnavailableError, LocalKekProvider, appLogKeyId, awsKms, equalBytes, opensKeyCheck };

package/dist/schemas.d.ts

@@ -9,8 +9,8 @@ export declare const principalType: z.ZodEnum<{
 }>;
 export declare const principalId: z.ZodString;
 export declare const instanceRole: z.ZodEnum<{
-  owner: "owner";
   user: "user";
+  owner: "owner";
 }>;
 export declare const grantId: z.ZodString;
 export declare const emailAddress: z.ZodString;

package/dist/vault.d.ts

@@ -155,6 +155,12 @@ export interface Vault {
     checkpointKeys: Record<string, CheckpointKey>;
     rootAdmins: string[];
   }>;
+  /**
+   * What an escrowed vault key is checked against: the vault key it wraps
+   * under now, and each one's check, as the vault wrote it. None of it is
+   * secret, and the vault answers no guess: a check opens only under its key.
+   */
+  keyChecks(): Promise<KeyChecks>;
   /**
    * Check the whole log: rehash it from the first entry, the vault's
    * entries by their MACs, every checkpoint against the prefix it signed,
@@ -234,6 +240,21 @@ export type WrappedKey = {
   kekVersion: string;
   bytes: string;
 };
+/**
+ * The vault key the vault wraps under now, by provider and ID, and each
+ * vault key's check, newest first: a known value wrapped under it
+ * (`KEY_CHECK_VALUE` in `@coffre/core/kek`), in its newest `key.check`
+ * entry that carries the vault's MAC, at `seq`.
+ */
+export type KeyChecks = {
+  current: {
+    kekProvider: string;
+    kekId: string;
+  };
+  checks: (WrappedKey & {
+    seq: number;
+  })[];
+};
 /** Why someone reads: shown in the log, and the same rules apply to each. */
 export type Purpose = 'reveal' | 'run' | 'compare' | 'sync';
 /** Ties the vault's entries to the app's request and audit rows. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/core",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "What coffre's packages share: roles, envelopes, identity, the audit chain and the vault's contract.",
   "license": "MIT",
   "repository": {
@@ -65,10 +65,11 @@
     "zod": "4.4.3"
   },
   "devDependencies": {
+    "@hegeldev/hegel": "0.4.7",
     "@types/node": "26.1.1",
     "tsdown": "0.23.0",
     "typescript": "5.9.3",
-    "@coffre/conformance": "0.1.6"
+    "@coffre/conformance": "0.1.7"
   },
   "scripts": {
     "build": "tsdown",

package/src/kek/check.ts

@@ -0,0 +1,46 @@
+// What a vault key, or the app key, can be checked against without opening
+// anything else: the vault's `key.check` entries, each a known value wrapped
+// under one vault key, and the key id the log records for the app's entries,
+// a fingerprint of the key they are signed with. The vault writes the
+// checks; `coffre verify keys` holds an escrowed key to them, on the
+// operator's machine, the key never sent anywhere.
+import { createHash } from 'node:crypto';
+
+import { deriveLogKey } from '../audit/chain.ts';
+import type { SecretContext } from '../context.ts';
+import { equalBytes, LocalKekProvider } from './local.ts';
+import { KekBadClaimError, type WrappedDek } from './types.ts';
+
+/** The action of the vault's entry that holds a vault key's check. */
+export const KEY_CHECK = 'key.check';
+
+/** The known value a check wraps: the size of a data key. */
+export const KEY_CHECK_VALUE: Buffer = createHash('sha256').update('coffre.kek.check.v1').digest();
+
+const NIL = '00000000-0000-0000-0000-000000000000';
+
+/** The context a check is wrapped in, which no secret has: the nil UUID throughout. */
+export const KEY_CHECK_CONTEXT: SecretContext = { projectId: NIL, environmentId: NIL, secretId: NIL };
+
+/**
+ * Whether `key`, a local vault key, is the one that wrapped `check`: it
+ * opens it, under the vault ID the check names, to the known value. The ID
+ * is bound into the wrap, so a match also says the ID is the escrowed one's.
+ */
+export async function opensKeyCheck(key: Buffer, check: WrappedDek): Promise<boolean> {
+  if (check.kekProvider !== 'local' || key.length !== 32) return false;
+  try {
+    const value = await new LocalKekProvider(key, check.kekId, check.kekVersion).unwrap(check, KEY_CHECK_CONTEXT);
+    const right = equalBytes(value, KEY_CHECK_VALUE);
+    value.fill(0);
+    return right;
+  } catch (error) {
+    if (error instanceof KekBadClaimError) return false;
+    throw error;
+  }
+}
+
+/** The id the log records for entries the app signs with `key`, its APP_KEY. */
+export function appLogKeyId(key: Uint8Array): string {
+  return deriveLogKey('app', key).keyId;
+}

package/src/kek/index.ts

@@ -3,4 +3,5 @@ export { DEK_BYTES, KekUnavailableError, KekCancelledError, KekBadClaimError } f
 export { LocalKekProvider, equalBytes } from './local.ts';
 export { KekRegistry } from './registry.ts';
 export { AwsKmsKekProvider, awsKms, type AwsKmsOptions } from './aws-kms.ts';
+export { appLogKeyId, KEY_CHECK, KEY_CHECK_CONTEXT, KEY_CHECK_VALUE, opensKeyCheck } from './check.ts';
 export type { AwsCredentials } from './sigv4.ts';

package/src/vault.ts

@@ -70,6 +70,12 @@ export interface Vault {
    * admins, as principals.
    */
   about(): Promise<{ checkpointKeys: Record<string, CheckpointKey>; rootAdmins: string[] }>;
+  /**
+   * What an escrowed vault key is checked against: the vault key it wraps
+   * under now, and each one's check, as the vault wrote it. None of it is
+   * secret, and the vault answers no guess: a check opens only under its key.
+   */
+  keyChecks(): Promise<KeyChecks>;
   /**
    * Check the whole log: rehash it from the first entry, the vault's
    * entries by their MACs, every checkpoint against the prefix it signed,
@@ -143,6 +149,14 @@ export type SecretRef = {
 /** A wrapped data key and the key encryption key that wrapped it; `bytes` is base64. */
 export type WrappedKey = { kekProvider: string; kekId: string; kekVersion: string; bytes: string };
 
+/**
+ * The vault key the vault wraps under now, by provider and ID, and each
+ * vault key's check, newest first: a known value wrapped under it
+ * (`KEY_CHECK_VALUE` in `@coffre/core/kek`), in its newest `key.check`
+ * entry that carries the vault's MAC, at `seq`.
+ */
+export type KeyChecks = { current: { kekProvider: string; kekId: string }; checks: (WrappedKey & { seq: number })[] };
+
 /** Why someone reads: shown in the log, and the same rules apply to each. */
 export type Purpose = 'reveal' | 'run' | 'compare' | 'sync';