@byok-sdk/core 0.30.0 → 0.30.2

package/dist/sealed-payload/member-key-record.d.ts

@@ -0,0 +1,61 @@
+import { type WebCryptoKey } from '../webcrypto';
+import { type P256PublicJwk } from './primitives';
+export declare const MEMBER_KEY_RECORD_VERSION = 1;
+/**
+ * Whose keys a store holds. A device member's binding names its SDK device
+ * id; a client member's has none, as in its bundle.
+ */
+export interface MemberKeyBinding {
+    readonly tenantId: string;
+    readonly deviceId?: string;
+}
+export interface MemberKeys {
+    readonly binding: MemberKeyBinding;
+    /** Signs chain entries and key packages. The private key is not extractable. */
+    readonly signing: {
+        readonly publicJwk: P256PublicJwk;
+        readonly privateKey: WebCryptoKey;
+    };
+    /** Opens key packages. The private key is not extractable. `epoch` starts at 1. */
+    readonly kem: MemberKemKey;
+    /** The KEM key of a rotation that has begun and not finished, at `kem.epoch + 1`. */
+    readonly nextKem?: MemberKemKey;
+}
+export interface MemberKemKey {
+    readonly epoch: number;
+    readonly publicJwk: P256PublicJwk;
+    readonly privateKey: WebCryptoKey;
+}
+/** The custody port of one member's keys. Each store expects one writer. */
+export interface MemberKeyStore {
+    /** The keys bound to `binding`, or `undefined` when the store holds none for it. A malformed record throws. */
+    load(binding: MemberKeyBinding): Promise<MemberKeys | undefined>;
+    /** The keys bound to `binding`. A store that holds none for it creates new ones, which replace any other binding's keys. */
+    loadOrCreate(binding: MemberKeyBinding): Promise<MemberKeys>;
+}
+/**
+ * A new member's record for `binding`: a fresh signing key and a fresh KEM
+ * key at epoch 1, as one canonical JSON text. The text holds both private
+ * scalars; only the member's own custody stores it.
+ */
+export declare function generateMemberKeyRecord(binding: MemberKeyBinding): Promise<string>;
+/**
+ * The keys of a stored record, imported non-extractable, or `undefined` when
+ * the text is not a canonical v1 record, or a private scalar does not match
+ * its public point. Never throws for hostile input.
+ */
+export declare function openMemberKeyRecord(text: unknown): Promise<MemberKeys | undefined>;
+/**
+ * Begin a KEM rotation: the record with a new KEM key at `kemEpoch + 1`
+ * beside the current one. A record whose rotation has begun comes back
+ * unchanged, so a resumed rotation keeps its key. A record that is not
+ * canonical v1 text throws.
+ */
+export declare function beginMemberKemRotation(text: string): Promise<string>;
+/**
+ * Finish the KEM rotation to `epoch`: the next key becomes current, and the
+ * old private key is gone from the record. A repeat after the rotation
+ * finished comes back unchanged. Any other `epoch` returns `undefined`. A
+ * record that is not canonical v1 text throws.
+ */
+export declare function finishMemberKemRotation(text: string, epoch: number): string | undefined;

package/dist/sealed-payload/scope-key.d.ts

@@ -10,6 +10,9 @@ export declare const SCOPE_KEY_PACKAGE_VERSION = 1;
 export declare const SCOPE_KEY_HPKE_INFO = "byok-sdk.scope-key.v1";
 /** Prepended to the canonical package bytes the sender signs. */
 export declare const SCOPE_KEY_PACKAGE_DOMAIN_PREFIX = "byok-scope-key-package-v1\n";
+export declare const SCOPE_KEY_PACKAGE_V2 = 2;
+export declare const SCOPE_KEY_HPKE_INFO_V2 = "byok-sdk.scope-key.v2";
+export declare const SCOPE_KEY_PACKAGE_V2_DOMAIN_PREFIX = "byok-scope-key-package-v2\n";
 /** A fresh scope key from the platform CSPRNG. */
 export declare function generateScopeKey(): Bytes;
 export declare function deriveScopeKeyId(scopeKey: Uint8Array): Promise<string>;
@@ -38,14 +41,22 @@ export interface ScopeKeyPackageV1 {
     /** Sender's ECDSA P-256 / SHA-256 signature, base64url of the 64-byte P1363 form. */
     readonly sig: string;
 }
+export interface ScopeKeyPackageV2 extends Omit<ScopeKeyPackageV1, 'v'> {
+    readonly v: typeof SCOPE_KEY_PACKAGE_V2;
+    /** The KEM epoch of the recipient key the package is wrapped to. */
+    readonly recipientKemEpoch: number;
+}
+export type ScopeKeyPackage = ScopeKeyPackageV1 | ScopeKeyPackageV2;
 export interface SealScopeKeyPackageInput {
     readonly scopeKey: Uint8Array;
     readonly tenantId: string;
     readonly scopeId: string;
     readonly epoch: number;
+    /** The recipient's current KEM key, with its epoch from the verified member chain. */
     readonly recipient: {
         readonly memberId: string;
         readonly kemPublicJwk: P256PublicJwk;
+        readonly kemEpoch: number;
     };
     readonly sender: {
         readonly signingPublicJwk: P256PublicJwk;
@@ -53,11 +64,11 @@ export interface SealScopeKeyPackageInput {
     };
 }
 /**
- * Wrap one scope key to one member and sign the package. A signing private key
- * that does not pair with `sender.signingPublicJwk` throws
- * `sealed_secret_invalid`.
+ * Wrap one scope key to one member's KEM key of `recipient.kemEpoch` and sign
+ * the version 2 package. A signing private key that does not pair with
+ * `sender.signingPublicJwk` throws `sealed_secret_invalid`.
  */
-export declare function sealScopeKeyPackage(input: SealScopeKeyPackageInput): Promise<ScopeKeyPackageV1>;
+export declare function sealScopeKeyPackage(input: SealScopeKeyPackageInput): Promise<ScopeKeyPackageV2>;
 export interface OpenScopeKeyPackageInput {
     readonly package: unknown;
     /** What the caller asked the Host for. A package for anything else is refused. */
@@ -70,6 +81,8 @@ export interface OpenScopeKeyPackageInput {
         readonly memberId: string;
         readonly kemPublicJwk: P256PublicJwk;
         readonly kemPrivateKey: WebCryptoKey;
+        /** The KEM epoch of this key pair. A version 2 package must name it. */
+        readonly kemEpoch: number;
     };
     /** The signing key the caller's verified chain holds for `package.sender`. */
     readonly senderSigningPublicJwk: P256PublicJwk;
@@ -84,7 +97,8 @@ export type ScopeKeyPackageOpenResult = {
 };
 /**
  * Verify and open one key package, in this order: shape; addressed to this
- * recipient for the expected tenant, scope and epoch; sender key matches the
+ * recipient (and, for version 2, its KEM epoch) for the expected tenant,
+ * scope and epoch; sender key matches the
  * sender id; sender signature; HPKE open; key length; and `keyId` equal to
  * the opened key's own id. Nothing here throws for hostile input.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byok-sdk/core",
-  "version": "0.30.0",
+  "version": "0.30.2",
   "description": "BYOK SDK platform contracts: branded tenant identity, tenant-first store ports, device proof canonicalization, and the composition conformance reference",
   "type": "module",
   "license": "MIT",