@serve.zone/interfaces 11.0.0 → 11.1.1

package/changelog.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 2026-07-13 - 11.1.1
+
+### Fixes
+
+- reject provider-reserved database names at isolated-restore prepare ingress
+  - Reject MongoDB system database names for both source and target mappings before a new restore reservation can be committed.
+  - Preserve structural decoding of historical mappings so cleanup and status remain available across the contract upgrade.
+
+## 2026-07-13 - 11.1.0
+
+### Features
+
+- define the hardened isolated-restore control contract (backup)
+  - Bind short-lived, single-operation restore grants to a canonical, versioned authority and immutable restore plan.
+  - Enforce JWT-only public authority, bounded chunk uploads, strict archive/resource normalization, and cross-runtime digest rules.
+  - Add bearer-free durable chunk receipts, completed-object proofs, and golden vectors for independent implementations.
+
 ## 2026-07-13 - 11.0.0
 
 ### Breaking Changes

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/interfaces',
-    version: '11.0.0',
+    version: '11.1.1',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLFFBQVE7SUFDakIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=

package/dist_ts/data/index.d.ts

@@ -11,6 +11,8 @@ export * from './externalregistry.js';
 export * from './gateway.js';
 export * from './hostedapp.js';
 export * from './image.js';
+export * from './isolatedrestore.js';
+export * from './isolatedrestore.golden.js';
 export * from './mail.js';
 export * from './registry.js';
 export * from './secretbundle.js';

package/dist_ts/data/index.js

@@ -11,6 +11,8 @@ export * from './externalregistry.js';
 export * from './gateway.js';
 export * from './hostedapp.js';
 export * from './image.js';
+export * from './isolatedrestore.js';
+export * from './isolatedrestore.golden.js';
 export * from './mail.js';
 export * from './registry.js';
 export * from './secretbundle.js';
@@ -27,4 +29,4 @@ export * from './taskexecution.js';
 export * from './traffic.js';
 export * from './user.js';
 export * from './version.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsVUFBVSxDQUFDO0FBQ3pCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsdUJBQXVCLENBQUM7QUFDdEMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLFdBQVcsQ0FBQztBQUMxQixjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLFdBQVcsQ0FBQztBQUMxQixjQUFjLGNBQWMsQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsVUFBVSxDQUFDO0FBQ3pCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsdUJBQXVCLENBQUM7QUFDdEMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsNkJBQTZCLENBQUM7QUFDNUMsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxjQUFjLENBQUMifQ==

package/dist_ts/data/isolatedrestore.d.ts

@@ -0,0 +1,315 @@
+import type { IBackupArchiveManifest, IBackupArchiveObject, TIsolatedRestoreResourceMapping } from './backup.js';
+/** Operations carried by a short-lived, single-operation restore grant. */
+export declare const isolatedRestoreGrantOperations: readonly ["prepare", "write-object", "execute", "cleanup", "status"];
+export type TIsolatedRestoreGrantOperation = (typeof isolatedRestoreGrantOperations)[number];
+/**
+ * Versioned limits shared by signers, relays, and Corestore.
+ *
+ * V1 uses an inline descriptor manifest inside a 1 MiB control request. Its
+ * 4,096 object slots reserve 256 entries for config, snapshots, keys, and
+ * index segments; the remaining 3,840 slots fit 1,920 default 8 MiB pack/index
+ * pairs. The 15 GiB total envelope is therefore reachable with the default
+ * ContainerArchive packing profile instead of advertising impossible capacity.
+ */
+export declare const isolatedRestoreContractLimits: Readonly<{
+    version: 1;
+    maximumControlJsonBytes: number;
+    maximumRestoreGrantBytes: number;
+    maximumConfiguredStringBytes: 2048;
+    maximumPathBytes: 4096;
+    maximumResourceMappings: 256;
+    maximumArchiveObjects: 4096;
+    reservedArchiveMetadataObjects: 256;
+    defaultContainerArchivePackTargetBytes: number;
+    maximumArchiveObjectBytes: number;
+    maximumArchiveTotalBytes: number;
+    maximumWriteChunkBytes: number;
+    maximumWriteChunkBase64Characters: 699052;
+    maximumObjectChunks: 4096;
+}>;
+/** ContainerArchive v1 paths that may be replicated into restore staging. */
+export declare const isolatedRestoreRepositoryPathProfile: Readonly<{
+    version: 1;
+    rootObject: "config.json";
+    topLevelDirectories: readonly ["packs", "snapshots", "index", "keys"];
+    temporaryFilesAllowed: false;
+    ancestorConflictsAllowed: false;
+}>;
+/**
+ * Exact normalized payload of a signed isolated restore grant.
+ * Persist this projection for audit/recovery, never the compact bearer JWT.
+ */
+export interface IIsolatedRestoreGrantClaims {
+    grantVersion: 1;
+    iss: string;
+    aud: string;
+    sub: string;
+    jti: string;
+    authorizationId: string;
+    tenantId: string;
+    clusterId: string;
+    targetNodeName: string;
+    restoreId: string;
+    sourceBackupId: string;
+    sourceServiceId: string;
+    scratchNamespaceId: string;
+    stagingArchiveId: string;
+    operation: TIsolatedRestoreGrantOperation;
+    resourceMappingsSha256: string;
+    archiveManifestSha256: string;
+    iat: number;
+    nbf: number;
+    exp: number;
+}
+declare const isolatedRestoreVerifiedGrantBrand: unique symbol;
+/**
+ * Runtime-branded result of invoking a cryptographic verifier for a compact
+ * restore grant. The bearer itself remains in module-private storage so this
+ * value cannot disclose it through serialization or reflection. It cannot be
+ * reconstructed from claims alone and is accepted only by the same module
+ * instance that performed verification.
+ */
+export interface IVerifiedIsolatedRestoreGrant {
+    readonly claims: Readonly<IIsolatedRestoreGrantClaims>;
+    readonly [isolatedRestoreVerifiedGrantBrand]: true;
+}
+export type TIsolatedRestoreGrantVerifier = (compactArg: string) => unknown | Promise<unknown>;
+/** The signed restoreGrant is the only authority accepted in control bodies. */
+export interface IIsolatedRestoreControlForbiddenAuthority {
+    authorizationId?: never;
+    tenantId?: never;
+    clusterId?: never;
+    targetNodeName?: never;
+    restoreId?: never;
+    sourceBackupId?: never;
+    sourceServiceId?: never;
+    targetServiceId?: never;
+    scratchNamespaceId?: never;
+    stagingArchiveId?: never;
+    operation?: never;
+    resourceMappingsSha256?: never;
+    archiveManifestSha256?: never;
+}
+export interface IIsolatedRestoreControlPrepareRequest extends IIsolatedRestoreControlForbiddenAuthority {
+    restoreGrant: string;
+    expectedRevision: number;
+    resourceMappings: TIsolatedRestoreResourceMapping[];
+    archiveManifest: IBackupArchiveManifest;
+}
+/**
+ * One bounded chunk of an immutable manifest object. `size` and `sha256`
+ * describe the complete object; `chunkSha256` authenticates this request's
+ * decoded bytes. Offset + decoded length === size means only that the chunk
+ * reaches the object boundary; it does not prove object completion.
+ */
+export interface IIsolatedRestoreControlWriteRequest extends IIsolatedRestoreControlForbiddenAuthority {
+    restoreGrant: string;
+    expectedRevision: number;
+    path: string;
+    size: number;
+    sha256: string;
+    offset: number;
+    chunkSha256: string;
+    contentsBase64: string;
+}
+export interface IIsolatedRestoreControlExecuteRequest extends IIsolatedRestoreControlForbiddenAuthority {
+    restoreGrant: string;
+    expectedRevision: number;
+}
+export interface IIsolatedRestoreControlCleanupRequest extends IIsolatedRestoreControlForbiddenAuthority {
+    restoreGrant: string;
+    expectedRevision: number;
+}
+export interface IIsolatedRestoreControlStatusRequest extends IIsolatedRestoreControlForbiddenAuthority {
+    restoreGrant: string;
+}
+export type TIsolatedRestoreControlRequest = IIsolatedRestoreControlPrepareRequest | IIsolatedRestoreControlWriteRequest | IIsolatedRestoreControlExecuteRequest | IIsolatedRestoreControlCleanupRequest | IIsolatedRestoreControlStatusRequest;
+/**
+ * Stable authority shared by every grant for one restore plan. Request-local
+ * operation, jti, and validity times are intentionally excluded so separately
+ * authorized write requests can contribute to the same object.
+ */
+export interface IIsolatedRestoreAuthorityProjection {
+    version: 1;
+    iss: string;
+    aud: string;
+    sub: string;
+    authorizationId: string;
+    tenantId: string;
+    clusterId: string;
+    targetNodeName: string;
+    restoreId: string;
+    sourceBackupId: string;
+    sourceServiceId: string;
+    scratchNamespaceId: string;
+    stagingArchiveId: string;
+    resourceMappingsSha256: string;
+    archiveManifestSha256: string;
+}
+export type TIsolatedRestoreBoundPrepareRequest = Omit<IIsolatedRestoreControlPrepareRequest, 'restoreGrant'>;
+export type TIsolatedRestoreBoundWriteRequestData = Omit<IIsolatedRestoreControlWriteRequest, 'restoreGrant'>;
+export type TIsolatedRestoreBoundExecuteRequest = Omit<IIsolatedRestoreControlExecuteRequest, 'restoreGrant'>;
+export type TIsolatedRestoreBoundCleanupRequest = Omit<IIsolatedRestoreControlCleanupRequest, 'restoreGrant'>;
+export type TIsolatedRestoreBoundStatusRequest = Omit<IIsolatedRestoreControlStatusRequest, 'restoreGrant'>;
+export interface IIsolatedRestoreBoundPlan {
+    authority: Readonly<IIsolatedRestoreAuthorityProjection>;
+    authoritySha256: string;
+    claims: Readonly<IIsolatedRestoreGrantClaims>;
+    resourceMappings: readonly TIsolatedRestoreResourceMapping[];
+    archiveManifest: Readonly<IBackupArchiveManifest>;
+}
+export interface IIsolatedRestoreBoundPrepareRequest {
+    authority: Readonly<IIsolatedRestoreAuthorityProjection>;
+    authoritySha256: string;
+    claims: Readonly<IIsolatedRestoreGrantClaims>;
+    request: Readonly<TIsolatedRestoreBoundPrepareRequest>;
+}
+export interface IIsolatedRestoreVerifiedChunkDescriptor {
+    contentsBase64: string;
+    decodedSize: number;
+    sha256: string;
+}
+export interface IIsolatedRestoreBoundWriteRequest {
+    authority: Readonly<IIsolatedRestoreAuthorityProjection>;
+    authoritySha256: string;
+    claims: Readonly<IIsolatedRestoreGrantClaims>;
+    request: Readonly<TIsolatedRestoreBoundWriteRequestData>;
+    descriptor: Readonly<IBackupArchiveObject>;
+    chunk: Readonly<IIsolatedRestoreVerifiedChunkDescriptor>;
+    /**
+     * The chunk reaches the declared size boundary. This is not object
+     * completion: only bindIsolatedRestoreCompletedObject proves contiguous
+     * coverage from offset 0 and the complete manifest-object SHA-256.
+     */
+    endsAtObjectSize: boolean;
+}
+export interface IIsolatedRestoreBoundControlRequest<TRequest extends object> {
+    authority: Readonly<IIsolatedRestoreAuthorityProjection>;
+    authoritySha256: string;
+    claims: Readonly<IIsolatedRestoreGrantClaims>;
+    request: Readonly<TRequest>;
+    plan: IIsolatedRestoreBoundPlan;
+}
+declare const isolatedRestoreCompletedObjectBrand: unique symbol;
+export interface IIsolatedRestoreCompletedObjectBinding {
+    readonly authority: Readonly<IIsolatedRestoreAuthorityProjection>;
+    readonly authoritySha256: string;
+    readonly descriptor: Readonly<IBackupArchiveObject>;
+    readonly chunkCount: number;
+    readonly contiguousBytes: number;
+    readonly sha256: string;
+    readonly [isolatedRestoreCompletedObjectBrand]: true;
+}
+/**
+ * Bearer-free receipt suitable for trusted Corestore persistence. Its hashes
+ * detect corruption and bind authority, descriptor, range, and chunk digest;
+ * they do not replace grant authentication or authenticate an untrusted store.
+ */
+export interface IIsolatedRestoreDurableChunkReceipt {
+    version: 1;
+    authority: Readonly<IIsolatedRestoreAuthorityProjection>;
+    authoritySha256: string;
+    descriptor: Readonly<IBackupArchiveObject>;
+    offset: number;
+    decodedSize: number;
+    chunkSha256: string;
+    receiptSha256: string;
+}
+/** Durable, bearer-free proof regenerated from receipts and one file snapshot. */
+export interface IIsolatedRestoreDurableCompletedObjectProof {
+    version: 1;
+    authority: Readonly<IIsolatedRestoreAuthorityProjection>;
+    authoritySha256: string;
+    descriptor: Readonly<IBackupArchiveObject>;
+    chunkCount: number;
+    contiguousBytes: number;
+    sha256: string;
+    receiptSetSha256: string;
+    proofSha256: string;
+}
+export declare class IsolatedRestoreContractError extends Error {
+    constructor(reasonArg: string);
+}
+/** Cross-runtime rules for restore authority digests. */
+export declare const isolatedRestoreCanonicalJsonRules: Readonly<{
+    version: 1;
+    encoding: "utf-8";
+    objectKeyOrdering: "utf-16-code-unit-ascending";
+    arrayOrdering: "preserved-dense";
+    unicodeNormalization: "preserved";
+    numberEncoding: "safe-integer-json-no-negative-zero";
+    digest: "sha256-lowercase-hex";
+}>;
+/**
+ * Enforces the raw HTTP ingress limit before buffering or JSON parsing.
+ * Apply it to Content-Length and to the running byte count after every chunk.
+ */
+export declare const assertIsolatedRestoreControlIngressByteLength: (byteLengthArg: unknown) => number;
+export declare const normalizeIsolatedRestoreResourceMappings: (valueArg: unknown) => TIsolatedRestoreResourceMapping[];
+/**
+ * Rejects names that the exact restore providers cannot provision, replace,
+ * or delete. Keep this separate from structural normalization so historical
+ * coordinator state remains readable for cleanup after a contract upgrade.
+ */
+export declare const assertIsolatedRestoreProviderRestorableResourceMappings: (mappingsArg: readonly TIsolatedRestoreResourceMapping[]) => void;
+export declare const normalizeIsolatedRestoreArchiveManifest: (valueArg: unknown) => IBackupArchiveManifest;
+export declare const normalizeIsolatedRestoreGrantClaims: (valueArg: unknown) => Readonly<IIsolatedRestoreGrantClaims>;
+export declare const normalizeIsolatedRestoreControlPrepareRequest: (valueArg: unknown) => IIsolatedRestoreControlPrepareRequest;
+export declare const normalizeIsolatedRestoreControlWriteRequest: (valueArg: unknown) => IIsolatedRestoreControlWriteRequest;
+export declare const normalizeIsolatedRestoreControlExecuteRequest: (valueArg: unknown) => IIsolatedRestoreControlExecuteRequest;
+export declare const normalizeIsolatedRestoreControlCleanupRequest: (valueArg: unknown) => IIsolatedRestoreControlCleanupRequest;
+export declare const normalizeIsolatedRestoreControlStatusRequest: (valueArg: unknown) => IIsolatedRestoreControlStatusRequest;
+export declare const canonicalizeIsolatedRestoreResourceMappings: (valueArg: readonly TIsolatedRestoreResourceMapping[]) => string;
+export declare const canonicalizeIsolatedRestoreArchiveManifest: (valueArg: IBackupArchiveManifest) => string;
+export declare const canonicalizeIsolatedRestoreGrantClaims: (valueArg: IIsolatedRestoreGrantClaims) => string;
+export declare const normalizeIsolatedRestoreAuthorityProjection: (valueArg: unknown) => Readonly<IIsolatedRestoreAuthorityProjection>;
+export declare const createIsolatedRestoreAuthorityProjection: (claimsArg: IIsolatedRestoreGrantClaims) => Readonly<IIsolatedRestoreAuthorityProjection>;
+export declare const canonicalizeIsolatedRestoreAuthorityProjection: (valueArg: IIsolatedRestoreAuthorityProjection) => string;
+export declare const createIsolatedRestoreBytesSha256: (contentsArg: Uint8Array) => Promise<string>;
+export declare const createIsolatedRestoreResourceMappingsSha256: (valueArg: unknown) => Promise<string>;
+export declare const createIsolatedRestoreArchiveManifestSha256: (valueArg: unknown) => Promise<string>;
+export declare const createIsolatedRestoreGrantClaimsSha256: (valueArg: unknown) => Promise<string>;
+export declare const createIsolatedRestoreAuthoritySha256: (valueArg: unknown) => Promise<string>;
+/**
+ * Invokes the caller's cryptographic verifier for exactly `compact`, retains
+ * that bearer in module-private storage, and brands the immutable claims
+ * projection. Binding helpers reject claims supplied without this operation
+ * and reject any control body carrying another compact JWT.
+ */
+export declare const verifyIsolatedRestoreGrant: (compactArg: unknown, verifierArg: TIsolatedRestoreGrantVerifier) => Promise<IVerifiedIsolatedRestoreGrant>;
+export declare const assertIsolatedRestoreGrantOperation: (grantArg: IVerifiedIsolatedRestoreGrant, expectedOperationArg: TIsolatedRestoreGrantOperation) => Readonly<IIsolatedRestoreGrantClaims>;
+export declare const bindIsolatedRestoreGrantToPlan: (grantArg: IVerifiedIsolatedRestoreGrant, expectedOperationArg: TIsolatedRestoreGrantOperation, resourceMappingsArg: unknown, archiveManifestArg: unknown) => Promise<IIsolatedRestoreBoundPlan>;
+export declare const bindIsolatedRestorePrepareRequestToGrant: (grantArg: IVerifiedIsolatedRestoreGrant, requestArg: unknown) => Promise<IIsolatedRestoreBoundPrepareRequest>;
+export declare const bindIsolatedRestoreExecuteRequestToGrant: (grantArg: IVerifiedIsolatedRestoreGrant, requestArg: unknown, resourceMappingsArg: unknown, archiveManifestArg: unknown) => Promise<IIsolatedRestoreBoundControlRequest<TIsolatedRestoreBoundExecuteRequest>>;
+export declare const bindIsolatedRestoreCleanupRequestToGrant: (grantArg: IVerifiedIsolatedRestoreGrant, requestArg: unknown, resourceMappingsArg: unknown, archiveManifestArg: unknown) => Promise<IIsolatedRestoreBoundControlRequest<TIsolatedRestoreBoundCleanupRequest>>;
+export declare const bindIsolatedRestoreStatusRequestToGrant: (grantArg: IVerifiedIsolatedRestoreGrant, requestArg: unknown, resourceMappingsArg: unknown, archiveManifestArg: unknown) => Promise<IIsolatedRestoreBoundControlRequest<TIsolatedRestoreBoundStatusRequest>>;
+export declare const bindIsolatedRestoreWriteRequestToGrant: (grantArg: IVerifiedIsolatedRestoreGrant, requestArg: unknown, resourceMappingsArg: unknown, archiveManifestArg: unknown) => Promise<IIsolatedRestoreBoundWriteRequest>;
+/** Returns a fresh caller-owned copy; verified bindings never expose mutable bytes. */
+export declare const decodeIsolatedRestoreBoundWriteChunk: (bindingArg: IIsolatedRestoreBoundWriteRequest) => Uint8Array;
+export declare const normalizeIsolatedRestoreDurableChunkReceipt: (valueArg: unknown) => Readonly<IIsolatedRestoreDurableChunkReceipt>;
+/**
+ * Rehydrates a trusted-store receipt and verifies both consistency digests.
+ * This does not replace verification of the grant that originally produced it.
+ */
+export declare const verifyIsolatedRestoreDurableChunkReceipt: (valueArg: unknown) => Promise<Readonly<IIsolatedRestoreDurableChunkReceipt>>;
+/**
+ * Creates a bearer-free receipt only from a runtime-verified write binding.
+ * Persist the result in authenticated/trusted Corestore state for recovery.
+ */
+export declare const createIsolatedRestoreDurableChunkReceipt: (bindingArg: IIsolatedRestoreBoundWriteRequest) => Promise<Readonly<IIsolatedRestoreDurableChunkReceipt>>;
+/**
+ * Rehydrates ordered trusted-store receipts and verifies them against one
+ * defensive snapshot of the complete staged file. Per-range and full-file
+ * SHA-256 checks bind the resulting proof to authority, object, and receipt set.
+ */
+export declare const verifyIsolatedRestoreDurableCompletedObject: (receiptsArg: readonly unknown[], contentsArg: Uint8Array) => Promise<Readonly<IIsolatedRestoreDurableCompletedObjectProof>>;
+/**
+ * Process-local completion convenience for runtime-branded chunks. It does not
+ * survive restart. Enterprise/Corestore workflows must persist durable chunk
+ * receipts and call verifyIsolatedRestoreDurableCompletedObject after recovery.
+ * Chunks must share one authority and descriptor, cover [0, size) contiguously,
+ * and hash to the complete manifest descriptor.
+ */
+export declare const bindIsolatedRestoreCompletedObject: (bindingsArg: readonly IIsolatedRestoreBoundWriteRequest[]) => Promise<IIsolatedRestoreCompletedObjectBinding>;
+export declare const assertIsolatedRestoreCompletedObject: (completedArg: IIsolatedRestoreCompletedObjectBinding) => IIsolatedRestoreCompletedObjectBinding;
+export {};

package/dist_ts/data/isolatedrestore.golden.d.ts

@@ -0,0 +1,18 @@
+import type { IBackupArchiveManifest, TIsolatedRestoreResourceMapping } from './backup.js';
+import type { IIsolatedRestoreGrantClaims } from './isolatedrestore.js';
+export interface IIsolatedRestoreCanonicalDigestGoldenVector<TInput> {
+    input: TInput;
+    canonicalJson: string;
+    sha256: string;
+}
+/**
+ * Portable fixed values for signer, relay, and verifier suites. The inputs
+ * deliberately cover an astral scalar, composed and decomposed accents, a
+ * quote, and a backslash. Consumers compare both JSON and SHA-256 verbatim.
+ */
+export declare const isolatedRestoreCanonicalDigestGoldenVectors: {
+    version: 1;
+    resourceMappings: IIsolatedRestoreCanonicalDigestGoldenVector<TIsolatedRestoreResourceMapping[]>;
+    archiveManifest: IIsolatedRestoreCanonicalDigestGoldenVector<IBackupArchiveManifest>;
+    grantClaims: IIsolatedRestoreCanonicalDigestGoldenVector<IIsolatedRestoreGrantClaims>;
+};

package/dist_ts/data/isolatedrestore.golden.js

@@ -0,0 +1,131 @@
+const deepFreezeVector = (valueArg) => {
+    if (!valueArg || typeof valueArg !== 'object' || Object.isFrozen(valueArg)) {
+        return valueArg;
+    }
+    for (const key of Reflect.ownKeys(valueArg)) {
+        const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+        if (descriptor && Object.hasOwn(descriptor, 'value')) {
+            deepFreezeVector(descriptor.value);
+        }
+    }
+    return Object.freeze(valueArg);
+};
+/**
+ * Portable fixed values for signer, relay, and verifier suites. The inputs
+ * deliberately cover an astral scalar, composed and decomposed accents, a
+ * quote, and a backslash. Consumers compare both JSON and SHA-256 verbatim.
+ */
+export const isolatedRestoreCanonicalDigestGoldenVectors = deepFreezeVector({
+    version: 1,
+    resourceMappings: {
+        input: [
+            {
+                id: 'mapping-volume',
+                type: 'volume',
+                source: {
+                    snapshotId: 'snapshot-volume',
+                    volumeName: 'source-volume',
+                    mountPath: '/srv/😀/é/"quoted"',
+                },
+                target: {
+                    volumeName: 'scratch-volume',
+                    mountPath: '/srv/😀/é/"quoted"',
+                },
+            },
+            {
+                id: 'mapping-database',
+                type: 'database',
+                source: {
+                    snapshotId: 'snapshot-database',
+                    resourceName: 'source-database-resource',
+                    databaseName: 'source_database',
+                },
+                target: {
+                    resourceName: 'scratch-database-resource',
+                    databaseName: 'scratch_database',
+                },
+            },
+            {
+                id: 'mapping-objectstorage',
+                type: 'objectstorage',
+                source: {
+                    snapshotId: 'snapshot-objectstorage',
+                    resourceName: 'source-objectstorage-resource',
+                    bucketName: 'source-bucket',
+                },
+                target: {
+                    resourceName: 'scratch-objectstorage-resource',
+                    bucketName: 'scratch-bucket',
+                },
+            },
+        ],
+        canonicalJson: '[{"id":"mapping-volume","source":{"mountPath":"/srv/😀/é/\\"quoted\\"","snapshotId":"snapshot-volume","volumeName":"source-volume"},"target":{"mountPath":"/srv/😀/é/\\"quoted\\"","volumeName":"scratch-volume"},"type":"volume"},' +
+            '{"id":"mapping-database","source":{"databaseName":"source_database","resourceName":"source-database-resource","snapshotId":"snapshot-database"},"target":{"databaseName":"scratch_database","resourceName":"scratch-database-resource"},"type":"database"},' +
+            '{"id":"mapping-objectstorage","source":{"bucketName":"source-bucket","resourceName":"source-objectstorage-resource","snapshotId":"snapshot-objectstorage"},"target":{"bucketName":"scratch-bucket","resourceName":"scratch-objectstorage-resource"},"type":"objectstorage"}]',
+        sha256: '3c084580fc258dcb5dc25b80d7331eb1d9072a124f640df3ce26eba4917afe70',
+    },
+    archiveManifest: {
+        input: {
+            version: 1,
+            backupId: 'backup-0001',
+            createdAt: 1700000000123,
+            objects: [
+                {
+                    path: 'config.json',
+                    size: 2,
+                    sha256: '0000000000000000000000000000000000000000000000000000000000000000',
+                },
+                {
+                    path: 'snapshots/snapshot-volume.json',
+                    size: 3,
+                    sha256: 'ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff',
+                },
+                {
+                    path: 'snapshots/snapshot-database.json',
+                    size: 5,
+                    sha256: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+                },
+                {
+                    path: 'snapshots/snapshot-objectstorage.json',
+                    size: 7,
+                    sha256: 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
+                },
+            ],
+            totalSize: 17,
+        },
+        canonicalJson: '{"backupId":"backup-0001","createdAt":1700000000123,"objects":[{"path":"config.json","sha256":"0000000000000000000000000000000000000000000000000000000000000000","size":2},' +
+            '{"path":"snapshots/snapshot-volume.json","sha256":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff","size":3},' +
+            '{"path":"snapshots/snapshot-database.json","sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","size":5},' +
+            '{"path":"snapshots/snapshot-objectstorage.json","sha256":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","size":7}],"totalSize":17,"version":1}',
+        sha256: 'cd688de1a4b7e0f0b185c660a2c0c199ea4009832c5614a49e8a4dec411f3bd4',
+    },
+    grantClaims: {
+        input: {
+            grantVersion: 1,
+            iss: 'urn:foss:restore:😀:é:é:"quoted":\\backslash',
+            aud: 'corestore.restore',
+            sub: 'cloudly-control',
+            jti: 'grant-0001',
+            authorizationId: 'authorization-0001',
+            tenantId: 'tenant-0001',
+            clusterId: 'cluster-eu-1',
+            targetNodeName: 'node-1',
+            restoreId: 'restore-0001',
+            sourceBackupId: 'backup-0001',
+            sourceServiceId: 'service-source',
+            scratchNamespaceId: 'scratch-0001',
+            stagingArchiveId: 'archive-0001',
+            operation: 'prepare',
+            resourceMappingsSha256: '3c084580fc258dcb5dc25b80d7331eb1d9072a124f640df3ce26eba4917afe70',
+            archiveManifestSha256: 'cd688de1a4b7e0f0b185c660a2c0c199ea4009832c5614a49e8a4dec411f3bd4',
+            iat: 2_000_000_000,
+            nbf: 2_000_000_000,
+            exp: 2_000_000_120,
+        },
+        canonicalJson: '{"archiveManifestSha256":"cd688de1a4b7e0f0b185c660a2c0c199ea4009832c5614a49e8a4dec411f3bd4","aud":"corestore.restore","authorizationId":"authorization-0001","clusterId":"cluster-eu-1","exp":2000000120,"grantVersion":1,"iat":2000000000,' +
+            '"iss":"urn:foss:restore:😀:é:é:\\"quoted\\":\\\\backslash","jti":"grant-0001","nbf":2000000000,"operation":"prepare","resourceMappingsSha256":"3c084580fc258dcb5dc25b80d7331eb1d9072a124f640df3ce26eba4917afe70",' +
+            '"restoreId":"restore-0001","scratchNamespaceId":"scratch-0001","sourceBackupId":"backup-0001","sourceServiceId":"service-source","stagingArchiveId":"archive-0001","sub":"cloudly-control","targetNodeName":"node-1","tenantId":"tenant-0001"}',
+        sha256: '6fcc94b4c6498b9fa45ec41de197999bbb38b9f8437a9c41f9c9478bdf3af8bf',
+    },
+});
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaXNvbGF0ZWRyZXN0b3JlLmdvbGRlbi5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2RhdGEvaXNvbGF0ZWRyZXN0b3JlLmdvbGRlbi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFZQSxNQUFNLGdCQUFnQixHQUFHLENBQUksUUFBVyxFQUFLLEVBQUU7SUFDN0MsSUFBSSxDQUFDLFFBQVEsSUFBSSxPQUFPLFFBQVEsS0FBSyxRQUFRLElBQUksTUFBTSxDQUFDLFFBQVEsQ0FBQyxRQUFRLENBQUMsRUFBRSxDQUFDO1FBQzNFLE9BQU8sUUFBUSxDQUFDO0lBQ2xCLENBQUM7SUFDRCxLQUFLLE1BQU0sR0FBRyxJQUFJLE9BQU8sQ0FBQyxPQUFPLENBQUMsUUFBa0IsQ0FBQyxFQUFFLENBQUM7UUFDdEQsTUFBTSxVQUFVLEdBQUcsTUFBTSxDQUFDLHdCQUF3QixDQUFDLFFBQWtCLEVBQUUsR0FBRyxDQUFDLENBQUM7UUFDNUUsSUFBSSxVQUFVLElBQUksTUFBTSxDQUFDLE1BQU0sQ0FBQyxVQUFVLEVBQUUsT0FBTyxDQUFDLEVBQUUsQ0FBQztZQUNyRCxnQkFBZ0IsQ0FBQyxVQUFVLENBQUMsS0FBSyxDQUFDLENBQUM7UUFDckMsQ0FBQztJQUNILENBQUM7SUFDRCxPQUFPLE1BQU0sQ0FBQyxNQUFNLENBQUMsUUFBUSxDQUFDLENBQUM7QUFDakMsQ0FBQyxDQUFDO0FBRUY7Ozs7R0FJRztBQUNILE1BQU0sQ0FBQyxNQUFNLDJDQUEyQyxHQVdwRCxnQkFBZ0IsQ0FBQztJQUNuQixPQUFPLEVBQUUsQ0FBQztJQUNWLGdCQUFnQixFQUFFO1FBQ2hCLEtBQUssRUFBRTtZQUNMO2dCQUNFLEVBQUUsRUFBRSxnQkFBZ0I7Z0JBQ3BCLElBQUksRUFBRSxRQUFRO2dCQUNkLE1BQU0sRUFBRTtvQkFDTixVQUFVLEVBQUUsaUJBQWlCO29CQUM3QixVQUFVLEVBQUUsZUFBZTtvQkFDM0IsU0FBUyxFQUFFLG9CQUFvQjtpQkFDaEM7Z0JBQ0QsTUFB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