@byok-sdk/core 0.28.3 → 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-chain.d.ts

@@ -0,0 +1,58 @@
+import { type JsonObject } from '../attestation';
+import type { WebCryptoKey } from '../webcrypto';
+import { type Bytes, type P256PublicJwk } from './primitives';
+/** Domain separation for {@link deriveMemberId}. */
+export declare const MEMBER_ID_DOMAIN = "byok-member-id-v1\n";
+/** `base64url(sha256(MEMBER_ID_DOMAIN || 0x04 || x || y))`: 43 characters, no padding. */
+export declare const MEMBER_ID_PATTERN: RegExp;
+export declare const MEMBER_CHAIN_VERSION = 1;
+/** Prepended to the canonical entry bytes, so a chain signature never verifies as another signed object. */
+export declare const MEMBER_CHAIN_DOMAIN_PREFIX = "byok-member-chain-v1\n";
+export declare const MEMBER_CHAIN_OPS: readonly ['add', 'remove', 'rotate', 'scope-policy', 'shred'];
+export type MemberChainOp = (typeof MEMBER_CHAIN_OPS)[number];
+/** One entry before it is signed. `seq` starts at 1; the first entry, and only it, has `prev: null`. */
+export interface UnsignedMemberChainEntryV1 {
+    readonly v: typeof MEMBER_CHAIN_VERSION;
+    readonly tenantId: string;
+    readonly seq: number;
+    /** `sha256:<hex>` of the previous entry's signing input. */
+    readonly prev: string | null;
+    readonly op: MemberChainOp;
+    readonly subject: JsonObject;
+    /** Member id of the signer. */
+    readonly signer: string;
+}
+export interface MemberChainEntryV1 extends UnsignedMemberChainEntryV1 {
+    /** ECDSA P-256 / SHA-256 over the signing input, base64url of the 64-byte P1363 form. */
+    readonly sig: string;
+}
+/** The member id of a signing public key. The key must be a point on P-256. */
+export declare function deriveMemberId(signingPublicJwk: P256PublicJwk): Promise<string>;
+/** `MEMBER_CHAIN_DOMAIN_PREFIX || canonicalJson(entry without sig)`. */
+export declare function memberChainSigningInput(entry: UnsignedMemberChainEntryV1): Bytes;
+/** `sha256:<hex>` of the signing input. The signature is not hashed, so the hash names the entry's content. */
+export declare function memberChainEntryHash(entry: UnsignedMemberChainEntryV1): Promise<string>;
+/**
+ * Sign one entry. The signer's public key is required so an entry is never
+ * signed under a member id that is not the signer's own. A private key that
+ * does not pair with that public key throws `sealed_secret_invalid`.
+ */
+export declare function signMemberChainEntry(entry: UnsignedMemberChainEntryV1, signer: {
+    readonly publicJwk: P256PublicJwk;
+    readonly privateKey: WebCryptoKey;
+}): Promise<MemberChainEntryV1>;
+export type MemberChainEntryVerifyResult = {
+    readonly ok: true;
+    readonly entry: MemberChainEntryV1;
+    readonly hash: string;
+} | {
+    readonly ok: false;
+    readonly reason: 'member_chain_entry_invalid' | 'member_chain_signature_invalid';
+};
+/**
+ * Verify one received entry against the signing key the verifier already
+ * pins for `entry.signer`. A malformed entry, or a key whose member id is not
+ * the entry's signer, is `member_chain_entry_invalid`; a bad signature is
+ * `member_chain_signature_invalid`. Nothing here throws for hostile input.
+ */
+export declare function verifyMemberChainEntry(entry: unknown, signerPublicJwk: P256PublicJwk): Promise<MemberChainEntryVerifyResult>;

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/primitives.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Byte helpers shared by the sealed-payload modules (#654 E1a).
+ *
+ * Every function is WebCrypto-only and `node:`-free, so a browser, Workers,
+ * Node and Bun run the same code. The subpath `@byok-sdk/core/sealed-payload`
+ * exports the sealed-payload interface, but not these helpers. The package
+ * root exports none of the sealed-payload modules.
+ *
+ * Caller input errors throw `sealed_secret_invalid`, the code `hpke.ts`
+ * already raises for bad HPKE input. Receiver checks never throw for hostile
+ * bytes; they return a typed failure.
+ */
+import { z } from 'zod';
+import { ByokCoreError } from '../errors';
+import { decodeBase64Url, encodeBase64Url, type SealingPublicJwk } from '../sealed-provider-secret';
+import { type WebCryptoKey } from '../webcrypto';
+export type Bytes = Uint8Array<ArrayBuffer>;
+/**
+ * The strict EC P-256 public JWK core already uses for sealing keys. Member
+ * signing keys and member KEM keys use the same shape.
+ */
+export type P256PublicJwk = SealingPublicJwk;
+export declare const P256PublicJwkSchema: z.ZodObject<{
+    kty: z.ZodLiteral<"EC">;
+    crv: z.ZodLiteral<"P-256">;
+    x: z.ZodString;
+    y: z.ZodString;
+}, z.core.$strict>;
+export declare function invalidInput(message: string): ByokCoreError;
+export declare function utf8(value: string): Bytes;
+export declare function copy(bytes: Uint8Array): Bytes;
+export declare function concat(...parts: readonly Uint8Array[]): Bytes;
+export declare function hex(bytes: Uint8Array): string;
+export { decodeBase64Url, encodeBase64Url };
+/** Fresh CSPRNG bytes from `globalThis.crypto`, the same source WebCrypto keys come from. */
+export declare function randomBytes(length: number): Bytes;
+export declare function sha256(bytes: Uint8Array): Promise<Bytes>;
+export declare function hmacSha256(key: Uint8Array, data: Uint8Array): Promise<Bytes>;
+/** RFC 5869 HKDF-SHA-256 through WebCrypto's own HKDF. */
+export declare function hkdfSha256(ikm: Uint8Array, salt: Uint8Array, info: string, length: number): Promise<Bytes>;
+/** A zod string that must be canonical unpadded base64url of exactly `bytes` bytes. */
+export declare function base64UrlBytes(bytes: number): z.ZodString;
+/** Uncompressed SEC1 bytes of a strict P-256 public JWK, checked to be a point on the curve. */
+export declare function p256PublicKeyBytes(publicJwk: P256PublicJwk): Promise<Bytes>;
+/**
+ * ECDSA P-256 / SHA-256 signature over `data`, as base64url of the 64-byte
+ * P1363 form. The signature must verify under `publicJwk`, so a private key
+ * that does not pair with the caller's public key throws
+ * `sealed_secret_invalid` and signs nothing under another key's id.
+ */
+export declare function ecdsaSign(publicJwk: P256PublicJwk, privateKey: WebCryptoKey, data: Uint8Array): Promise<string>;
+/** True only for a canonical 64-byte P1363 signature that verifies under `publicJwk`. */
+export declare function ecdsaVerify(publicJwk: P256PublicJwk, signature: string, data: Uint8Array): Promise<boolean>;

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

@@ -0,0 +1,91 @@
+import type { WebCryptoKey } from '../webcrypto';
+import { type Bytes, type P256PublicJwk } from './primitives';
+export declare const SCOPE_KEY_BYTES = 32;
+/** 16 bytes of the key-id HMAC, as unpadded base64url. */
+export declare const SCOPE_KEY_ID_LENGTH = 22;
+export declare const SCOPE_KEY_ID_PATTERN: RegExp;
+/** Byte length of the per-content HKDF salt. */
+export declare const SEALED_SALT_BYTES = 32;
+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";
+/** A fresh scope key from the platform CSPRNG. */
+export declare function generateScopeKey(): Bytes;
+export declare function deriveScopeKeyId(scopeKey: Uint8Array): Promise<string>;
+/** The AES-256-GCM key of one sealed content. Each content has its own salt, so each key encrypts once. */
+export declare function deriveSealedContentKey(scopeKey: Uint8Array, salt: Uint8Array): Promise<Bytes>;
+/**
+ * The content-MAC key of one scope epoch. The design's salt is empty; HMAC
+ * pads its key with zeros, so 32 zero bytes give the same output, and no
+ * runtime has to accept a zero-length HKDF salt.
+ */
+export declare function deriveSealedMacKey(scopeKey: Uint8Array): Promise<Bytes>;
+export interface ScopeKeyPackageV1 {
+    readonly v: typeof SCOPE_KEY_PACKAGE_VERSION;
+    readonly tenantId: string;
+    readonly scopeId: string;
+    readonly epoch: number;
+    readonly keyId: string;
+    /** Member id of the member that can open the package. */
+    readonly recipient: string;
+    /** Member id of the member that sealed and signed the package. */
+    readonly sender: string;
+    /** HPKE encapsulated key: base64url of a 65-byte uncompressed P-256 point. */
+    readonly enc: string;
+    /** HPKE ciphertext of the scope key: base64url of 48 bytes. */
+    readonly ciphertext: string;
+    /** Sender's ECDSA P-256 / SHA-256 signature, base64url of the 64-byte P1363 form. */
+    readonly sig: string;
+}
+export interface SealScopeKeyPackageInput {
+    readonly scopeKey: Uint8Array;
+    readonly tenantId: string;
+    readonly scopeId: string;
+    readonly epoch: number;
+    readonly recipient: {
+        readonly memberId: string;
+        readonly kemPublicJwk: P256PublicJwk;
+    };
+    readonly sender: {
+        readonly signingPublicJwk: P256PublicJwk;
+        readonly signingPrivateKey: WebCryptoKey;
+    };
+}
+/**
+ * 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`.
+ */
+export declare function sealScopeKeyPackage(input: SealScopeKeyPackageInput): Promise<ScopeKeyPackageV1>;
+export interface OpenScopeKeyPackageInput {
+    readonly package: unknown;
+    /** What the caller asked the Host for. A package for anything else is refused. */
+    readonly expected: {
+        readonly tenantId: string;
+        readonly scopeId: string;
+        readonly epoch: number;
+    };
+    readonly recipient: {
+        readonly memberId: string;
+        readonly kemPublicJwk: P256PublicJwk;
+        readonly kemPrivateKey: WebCryptoKey;
+    };
+    /** The signing key the caller's verified chain holds for `package.sender`. */
+    readonly senderSigningPublicJwk: P256PublicJwk;
+}
+export type ScopeKeyPackageOpenResult = {
+    readonly ok: true;
+    readonly scopeKey: Uint8Array;
+    readonly keyId: string;
+} | {
+    readonly ok: false;
+    readonly reason: 'key_package_invalid' | 'key_package_signature_invalid' | 'key_package_open_failed';
+};
+/**
+ * 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
+ * sender id; sender signature; HPKE open; key length; and `keyId` equal to
+ * the opened key's own id. Nothing here throws for hostile input.
+ */
+export declare function openScopeKeyPackage(input: OpenScopeKeyPackageInput): Promise<ScopeKeyPackageOpenResult>;

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>;