@byok-sdk/core 0.29.0 → 0.30.0

package/dist/sealed-payload/member-bundle.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The member key bundle (#654 design §7.1, §7.2, E2b; owner decision 10a).
+ *
+ * A bundle is the public half of one member: its id, its ECDSA P-256 signing
+ * key, its P-256 KEM key, the KEM epoch, and `kemSig`. A device member also
+ * names its SDK device id. A client member does not.
+ *
+ * `kemSig` is the member's own signature over its KEM key and epoch. The
+ * fingerprint covers only the signing key, so a KEM rotation keeps the member
+ * id and the fingerprint. The self-signature binds the KEM key to the member:
+ * a Host that swaps the KEM key breaks the signature.
+ *
+ * An `add` chain entry carries the bundle. The pairing MACs bind it. In a
+ * later slice, the device registers it with device proof.
+ */
+import { z } from 'zod';
+import type { WebCryptoKey } from '../webcrypto';
+import { type Bytes, type P256PublicJwk } from './primitives';
+export declare const MEMBER_KEY_BUNDLE_VERSION = 1;
+/** Prepended to the canonical KEM statement, so `kemSig` never verifies as another signed object. */
+export declare const MEMBER_KEM_DOMAIN_PREFIX = "byok-member-kem-v1\n";
+export interface MemberKeyBundleV1 {
+    readonly v: typeof MEMBER_KEY_BUNDLE_VERSION;
+    readonly memberId: string;
+    readonly signingPublicJwk: P256PublicJwk;
+    readonly kemPublicJwk: P256PublicJwk;
+    readonly kemEpoch: number;
+    /** ECDSA P-256 / SHA-256 by the signing key over the KEM statement, base64url of the 64-byte P1363 form. */
+    readonly kemSig: string;
+    /** The SDK device id of a device member. A client member has none. */
+    readonly deviceId?: string;
+}
+export declare const KemEpochSchema: z.ZodNumber;
+export declare const KemSigSchema: z.ZodString;
+/** `MEMBER_KEM_DOMAIN_PREFIX || canonicalJson({ memberId, kemPublicKey: { x, y }, kemEpoch })`. */
+export declare function memberKemSigningInput(memberId: string, kemPublicJwk: P256PublicJwk, kemEpoch: number): Bytes;
+export interface CreateMemberKeyBundleInput {
+    readonly signingPublicJwk: P256PublicJwk;
+    readonly signingPrivateKey: WebCryptoKey;
+    readonly kemPublicJwk: P256PublicJwk;
+    readonly kemEpoch: number;
+    readonly deviceId?: string;
+}
+/** Build a bundle: derive the member id and sign the KEM statement. Bad input throws `sealed_secret_invalid`. */
+export declare function createMemberKeyBundle(input: CreateMemberKeyBundleInput): Promise<MemberKeyBundleV1>;
+/** Both keys are points on P-256, and the KEM key is not the signing key. */
+export declare function isValidMemberKemKey(kemPublicJwk: P256PublicJwk, signingPublicJwk: P256PublicJwk): Promise<boolean>;
+/** The KEM key is valid for the member, and `kemSig` is the member's signature over it. Never throws. */
+export declare function verifyMemberKem(member: {
+    readonly memberId: string;
+    readonly signingPublicJwk: P256PublicJwk;
+}, kem: {
+    readonly kemPublicJwk: P256PublicJwk;
+    readonly kemEpoch: number;
+    readonly kemSig: string;
+}): Promise<boolean>;
+/**
+ * Parse a received bundle. It is valid when its shape is strict, `memberId`
+ * is the id of `signingPublicJwk` (which also checks that key is on the
+ * curve), the KEM key is a different point on the curve, and `kemSig`
+ * verifies. Returns `undefined` for anything else; it never throws for
+ * hostile input.
+ */
+export declare function parseMemberKeyBundle(value: unknown): Promise<MemberKeyBundleV1 | undefined>;

package/dist/sealed-payload/member-chain-walk.d.ts

@@ -0,0 +1,77 @@
+import { type MemberKeyBundleV1 } from './member-bundle';
+import { type P256PublicJwk } from './primitives';
+import { type SealedCategory } from './sealed-content';
+export interface MemberChainScope {
+    readonly categories: readonly SealedCategory[];
+    /** Member ids from the latest `scope-policy` entry, sorted. Some may be removed since. */
+    readonly members: readonly string[];
+    /** `seq` of that entry. */
+    readonly policySeq: number;
+}
+export interface MemberChainHead {
+    readonly seq: number;
+    readonly hash: string;
+}
+export interface MemberChainState {
+    readonly tenantId: string;
+    /** `null` before the genesis entry. */
+    readonly head: MemberChainHead | null;
+    /** Current members by member id, with their current KEM key. */
+    readonly members: ReadonlyMap<string, MemberKeyBundleV1>;
+    readonly removed: ReadonlySet<string>;
+    readonly scopes: ReadonlyMap<string, MemberChainScope>;
+    readonly shredded: ReadonlySet<string>;
+}
+export type MemberChainWalkFailure = 'member_chain_entry_invalid' | 'member_chain_link_invalid' | 'member_chain_signer_invalid' | 'member_chain_signature_invalid' | 'member_chain_subject_invalid';
+export type MemberChainWalkResult = {
+    readonly ok: true;
+    readonly state: MemberChainState;
+} | {
+    readonly ok: false;
+    readonly reason: MemberChainWalkFailure;
+    readonly index: number;
+};
+/** The state before the genesis entry of `tenantId`'s chain. */
+export declare function emptyMemberChainState(tenantId: string): MemberChainState;
+/** The latest policy's members that are still current: the members that get key packages for the scope. */
+export declare function memberChainScopeRecipients(state: MemberChainState, scopeId: string): readonly MemberKeyBundleV1[];
+/** Apply `entries` in order after `state`. Never throws for hostile entries. */
+export declare function applyMemberChainEntries(state: MemberChainState, entries: readonly unknown[]): Promise<MemberChainWalkResult>;
+export type MemberChainAnchorFailure = MemberChainWalkFailure | 'member_chain_anchor_missing' | 'member_chain_head_mismatch';
+export type MemberChainAnchorResult = {
+    readonly ok: true;
+    readonly state: MemberChainState;
+    /** `seq` of the anchor entry: the `add` of this member, signed by the pinned approver. */
+    readonly anchorSeq: number;
+} | {
+    readonly ok: false;
+    readonly reason: MemberChainAnchorFailure;
+    readonly index?: number;
+};
+export interface VerifyMemberChainFromAnchorInput {
+    readonly tenantId: string;
+    /** The whole chain, from the genesis entry (seq 1). */
+    readonly entries: readonly unknown[];
+    /** This member's own bundle, exactly as it was approved. */
+    readonly self: MemberKeyBundleV1;
+    /** The approver's signing key, pinned out of band: by the pv MAC or by the two-way fingerprint (10a). */
+    readonly approverSigningPublicJwk: P256PublicJwk;
+    /**
+     * A chain head the approver authenticated out of band, for example the
+     * head in the client pairing MAC. When given, it must be the anchor entry.
+     */
+    readonly authenticatedHead?: MemberChainHead;
+}
+/**
+ * Verify a chain as a member that joined after the genesis entry (11b):
+ *
+ * 1. The member pins the approver's signing key K out of band.
+ * 2. Entry E is an `add` whose `member` is byte-identical to `self` (KEM key
+ *    included) and whose signer is `memberId(K)`, verified with K.
+ * 3. The walk from genesis reaches E, so E is on the chain path.
+ * 4. The entries after E verify forward by signature.
+ *
+ * The first E counts; `self` can be added only once. Never throws for
+ * hostile entries.
+ */
+export declare function verifyMemberChainFromAnchor(input: VerifyMemberChainFromAnchorInput): Promise<MemberChainAnchorResult>;

package/dist/sealed-payload/member-fingerprint.d.ts

@@ -0,0 +1,14 @@
+import { type P256PublicJwk } from './primitives';
+export declare const MEMBER_FINGERPRINT_DOMAIN = "byok-member-fingerprint-v1\n";
+export interface MemberFingerprintInput {
+    readonly tenantId: string;
+    readonly signingPublicJwk: P256PublicJwk;
+}
+/** The 25-digit fingerprint of one member, as 5 groups of 5 digits joined by single spaces. */
+export declare function memberFingerprint(input: MemberFingerprintInput): Promise<string>;
+/**
+ * The 50-digit two-way approval code of two members of one tenant: their
+ * fingerprints ordered by member id, as 10 groups of 5 digits joined by
+ * single spaces. The order of the arguments does not matter.
+ */
+export declare function memberApprovalCode(tenantId: string, first: P256PublicJwk, second: P256PublicJwk): Promise<string>;

package/dist/sealed-payload/pairing-verification.d.ts

@@ -0,0 +1,51 @@
+import type { MemberKeyBundleV1 } from './member-bundle';
+import { type Bytes } from './primitives';
+export declare const PAIRING_VERIFICATION_SECRET_BYTES = 16;
+export declare const PAIRING_VERIFICATION_TEXT_LENGTH = 26;
+/** 128 fresh CSPRNG bits. */
+export declare function generatePairingVerificationSecret(): Bytes;
+export declare function encodePairingVerificationSecret(pv: Uint8Array): string;
+export declare function decodePairingVerificationSecret(text: string): Bytes;
+/** `<pairingCode>.<pv>`, the string the client shows and the user gives to the device. */
+export declare function formatPairingInput(pairingCode: string, pv: Uint8Array): string;
+export interface PairingInput {
+    /** The only part the device sends to the Host. */
+    readonly pairingCode: string;
+    /** Kept on the device; never sent to the Host. */
+    readonly pv: Bytes;
+}
+/** Split `<pairingCode>.<pv>` on the last `.`. Both parts are required. */
+export declare function parsePairingInput(text: string): PairingInput;
+/** Domain tag of the MAC the device sends: step 3, `HMAC(pv, device bundle, tenantId, deviceId)`. */
+export declare const DEVICE_PAIRING_MAC_DOMAIN = "byok-pairing-device-mac-v1\n";
+/** Domain tag of the MAC the client sends: step 4, `HMAC(pv, client bundle, chain head)`. */
+export declare const CLIENT_PAIRING_MAC_DOMAIN = "byok-pairing-client-mac-v1\n";
+export interface DevicePairingMacInput {
+    readonly tenantId: string;
+    readonly deviceId: string;
+    /** The device's own bundle. Its `deviceId` must equal `deviceId`. */
+    readonly member: MemberKeyBundleV1;
+}
+export interface ClientPairingMacInput {
+    /** The client's own bundle. A client bundle has no `deviceId`. */
+    readonly member: MemberKeyBundleV1;
+    /** The chain head after the client signed `add(device)`. */
+    readonly chainHead: {
+        readonly seq: number;
+        readonly hash: string;
+    };
+}
+export declare function computeDevicePairingMac(pv: Uint8Array, input: DevicePairingMacInput): Promise<string>;
+export declare function computeClientPairingMac(pv: Uint8Array, input: ClientPairingMacInput): Promise<string>;
+/**
+ * Check a received device MAC. Parse the received bundle with
+ * `parseMemberKeyBundle` first. Returns `false` for a wrong or malformed MAC,
+ * or a bundle that does not name `deviceId`. Only a malformed `pv` throws.
+ */
+export declare function verifyDevicePairingMac(pv: Uint8Array, input: DevicePairingMacInput, mac: unknown): Promise<boolean>;
+/**
+ * Check a received client MAC. Parse the received bundle with
+ * `parseMemberKeyBundle` first. Returns `false` for a wrong or malformed MAC,
+ * a device bundle, or a malformed chain head. Only a malformed `pv` throws.
+ */
+export declare function verifyClientPairingMac(pv: Uint8Array, input: ClientPairingMacInput, mac: unknown): Promise<boolean>;

package/dist/sealed-payload/sealed-blob.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Sealed blob bytes v1 (#654 design §8.1, E1c).
+ *
+ * A protocol field blob (`instruction.blobRef`, a progress spill, an artifact)
+ * is sealed before its outer content, by the same frame, key and AEAD rule.
+ * Its AAD is the 16 outer AAD members that do not depend on the outer
+ * plaintext, the blob's own `paddedLength`, and `fieldPath`: the RFC 6901
+ * JSON Pointer from the moved-fields object to its BlobRef. The blob's salt,
+ * nonce and padded length travel next to the BlobRef inside the outer
+ * plaintext, so the outer AEAD and content MAC cover them.
+ *
+ * Internal: the subpath index does not import this module, so it adds no
+ * bytes to the published closure.
+ */
+import { z } from 'zod';
+import { type SealedBinding, type SealedCategory, type SealedContentHeaderV1, type SealedContentOpenFailure, type SealedContentRandomness } from './sealed-content';
+/** What the outer plaintext carries next to a sealed blob's BlobRef. */
+export declare const SealedBlobParamsV1Schema: z.ZodObject<{
+    salt: z.ZodString;
+    nonce: z.ZodString;
+    paddedLength: z.ZodNumber;
+}, z.core.$strict>;
+export type SealedBlobParamsV1 = z.infer<typeof SealedBlobParamsV1Schema>;
+/**
+ * The canonical AAD bytes of a blob sealed under an outer header (§8.1).
+ */
+export declare function sealedBlobAad(header: SealedContentHeaderV1, binding: SealedBinding, paddedLength: number, fieldPath: string): Uint8Array;
+/**
+ * The input of one blob seal. Scope, chain head, sender, category and binding
+ * must be the ones of the outer content that will carry the BlobRef.
+ */
+export interface SealBlobInput {
+    readonly scopeKey: Uint8Array;
+    readonly scope: {
+        readonly id: string;
+        readonly epoch: number;
+    };
+    readonly chainHead: {
+        readonly seq: number;
+        readonly hash: string;
+    };
+    readonly sender: string;
+    readonly category: SealedCategory;
+    readonly binding: SealedBinding;
+    /** The pointer to the BlobRef node in the moved-fields object. */
+    readonly fieldPath: string;
+    /** The raw blob bytes. */
+    readonly bytes: Uint8Array;
+    /** The plaintext limit of this field, in bytes. */
+    readonly maxContentLength: number;
+}
+export interface SealedBlob {
+    readonly params: SealedBlobParamsV1;
+    /** AES-256-GCM output: the padded frame followed by the 16-byte tag. Upload these bytes. */
+    readonly ciphertext: Uint8Array;
+}
+/**
+ * Seal one blob once, before the outer content. A retry must reuse the
+ * uploaded blob, never seal again (§8.6).
+ */
+export declare function sealBlob(input: SealBlobInput): Promise<SealedBlob>;
+/**
+ * {@link sealBlob} with a caller-chosen salt and nonce, for test vectors only.
+ */
+export declare function sealBlobWithRandomness(input: SealBlobInput, randomness: SealedContentRandomness): Promise<SealedBlob>;
+export interface OpenSealedBlobInput {
+    /** The outer header that `openSealedContent` authenticated. */
+    readonly header: SealedContentHeaderV1;
+    /** The binding the outer content opened under. */
+    readonly binding: SealedBinding;
+    readonly scopeKey: Uint8Array;
+    /** The receiver derives it from where it found the BlobRef, never from a table. */
+    readonly fieldPath: string;
+    /** From the opened outer plaintext. Its shape is still checked here. */
+    readonly params: unknown;
+    /** The downloaded blob bytes. The caller checks the BlobRef `contentHash` against them (§9.3). */
+    readonly ciphertext: Uint8Array;
+    readonly maxContentLength: number;
+}
+export type SealedBlobOpenResult = {
+    readonly ok: true;
+    readonly bytes: Uint8Array;
+} | {
+    readonly ok: false;
+    readonly reason: SealedContentOpenFailure;
+};
+/**
+ * Open one blob, fail closed. In order: binding and category
+ * (`sealing_policy_mismatch`); header, field path and params shape
+ * (`sealed_open_failed`); key id (`sealed_key_unavailable`); ciphertext
+ * length, AEAD under the rebuilt blob AAD and the five frame checks (all
+ * `sealed_open_failed`). Nothing here throws for hostile input.
+ */
+export declare function openSealedBlob(input: OpenSealedBlobInput): Promise<SealedBlobOpenResult>;

package/dist/sealed-payload/sealed-content.d.ts

@@ -22,8 +22,9 @@
  * `contentMac` is a keyed MAC over category, family, identity and plaintext. The
  * Host compares two submissions of one identity by it, without a key.
  *
- * Blob fields are not sealed here yet; their AAD rule comes with the blob wire
- * rules.
+ * A blob field is sealed by the same frame and key rule, before its outer
+ * content. Its AAD is the outer AAD without `paddedLength` and `contentMac`,
+ * plus its own `paddedLength` and the JSON Pointer `fieldPath` to its BlobRef.
  */
 import { z } from 'zod';
 import { type JsonObject } from '../attestation';

package/dist/sealed-payload/sealed-json.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Canonical JSON of a sealed plaintext (#786): RFC 8785 with its full number
+ * rule.
+ *
+ * Keys sort by UTF-16 code unit and strings use the ECMAScript serialization,
+ * the same as `canonicalizeJson`. Numbers differ. A finite number serializes
+ * as `Number.prototype.toString` (RFC 8785 §3.2.2.3), so a decimal, an
+ * exponent and an integer above 2^53 are sealable. `-0` serializes as `0`.
+ * NaN and the infinities have no JSON form and throw.
+ *
+ * Only the sealed plaintext uses this rule. The AAD, the MAC identity, member
+ * chain entries and key packages keep `canonicalizeJson`, whose safe-integer
+ * rule belongs to the attestation contract.
+ */
+import type { JsonValue } from '../attestation';
+/** The canonical JSON text of a sealed plaintext value. Throws `sealed_secret_invalid` outside JSON. */
+export declare function canonicalizeSealedJson(value: JsonValue): string;

package/dist/total-parse.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A zod parse that never throws.
+ *
+ * `safeParse` returns a failure for invalid data, but it does not catch an
+ * error that a getter or a proxy trap throws while zod reads the value, and a
+ * revoked proxy throws on any read. A receiver that promises a typed result
+ * for hostile input, or a typed error for bad caller input, parses through
+ * this. Wire input from `JSON.parse` cannot hold getters or proxies; this
+ * closes the same gap for in-process callers.
+ */
+import type { z } from 'zod';
+export type TotalParseResult<T> = {
+    readonly success: true;
+    readonly data: T;
+} | {
+    readonly success: false;
+    readonly error?: z.ZodError;
+};
+/** `schema.safeParse(value)`, with a throw while reading `value` as a failure without issues. */
+export declare function safeParseTotal<S extends z.ZodType>(schema: S, value: unknown): TotalParseResult<z.output<S>>;

package/package.json

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