spawnfile 0.1.12 → 0.1.14

package/dist/auth/targetSecretSourceGrant.js

@@ -0,0 +1,99 @@
+import { TARGET_SECRET_SOURCE_ERROR } from "./targetSecretSourceRecordCommon.js";
+import { initializeTargetSecretSourceFsRead } from "./targetSecretSourceFsRead.js";
+import { createTargetSecretSourceGrantRecordBytes, createTargetSecretSourceGrantMetadata } from "./targetSecretSourceGrantRecords.js";
+import { initializeTargetSecretSourceRecordPublish } from "./targetSecretSourceRecordPublish.js";
+import { deriveTargetSecretSourceOwnerEntropy } from "./targetSecretSourceOwnerEntropy.js";
+import { assertTargetSecretSourceAliasCorrelation } from "./targetSecretSourceVersionRecords.js";
+const fail = () => { throw new Error(TARGET_SECRET_SOURCE_ERROR); };
+const sameGrant = (left, right) => left.descriptor_digest === right.descriptor_digest
+    && left.name === right.name
+    && left.run_id === right.run_id
+    && left.scope === right.scope
+    && left.source_handle === right.source_handle
+    && left.source_version_handle === right.source_version_handle
+    && left.selected_target.fingerprint === right.selected_target.fingerprint
+    && left.selected_target.handle === right.selected_target.handle
+    && left.selected_target.version === right.selected_target.version;
+export const initializeTargetSecretSourceGrant = async (options = {}) => {
+    const reader = options.reader ?? await initializeTargetSecretSourceFsRead();
+    const publisher = options.publisher ?? await initializeTargetSecretSourceRecordPublish();
+    return Object.freeze({
+        grantSource: async (input) => {
+            let versionSecret;
+            let grantBytes;
+            try {
+                const alias = await reader.readAlias(input?.source_handle);
+                if (!alias)
+                    return fail();
+                const version = await reader.readVersion(alias.source_version_handle);
+                if (!version)
+                    return fail();
+                versionSecret = version.secret;
+                const aliasMetadata = {
+                    source_handle: alias.source_handle,
+                    source_version_handle: alias.source_version_handle,
+                    version: alias.version
+                };
+                const versionMetadata = {
+                    source_version_handle: version.source_version_handle,
+                    version: version.version
+                };
+                assertTargetSecretSourceAliasCorrelation(aliasMetadata, versionMetadata);
+                if (alias.publication_handle === version.publication_handle)
+                    fail();
+                const assertNotRevoked = async () => {
+                    const [grantRevocation, versionRevocation] = await Promise.all([
+                        reader.readRevocation(alias.source_handle),
+                        reader.readRevocation(alias.source_version_handle)
+                    ]);
+                    if (grantRevocation || versionRevocation)
+                        fail();
+                };
+                await assertNotRevoked();
+                const expected = createTargetSecretSourceGrantMetadata({
+                    ...input,
+                    source_handle: alias.source_handle,
+                    source_version_handle: alias.source_version_handle
+                });
+                let existing;
+                try {
+                    existing = await reader.readGrant(alias.source_handle);
+                }
+                catch {
+                    existing = null;
+                }
+                if (existing) {
+                    if (!sameGrant(existing, expected))
+                        fail();
+                    await assertNotRevoked();
+                    return Object.freeze({ source_handle: alias.source_handle });
+                }
+                const { version: _grantVersion, ...grantInput } = expected;
+                const grant = createTargetSecretSourceGrantRecordBytes(grantInput, {
+                    publicationEntropy: options.publicationEntropy
+                        ?? (() => deriveTargetSecretSourceOwnerEntropy("grant.publication_handle", expected))
+                });
+                grantBytes = grant.private_bytes;
+                if (grant.private_metadata.publication_handle === alias.publication_handle
+                    || grant.private_metadata.publication_handle === version.publication_handle)
+                    fail();
+                try {
+                    await publisher.publishGrant(grantBytes);
+                }
+                catch { /* prove the durable result below */ }
+                const joined = await reader.readGrant(alias.source_handle);
+                if (!joined || !sameGrant(joined, grant.metadata))
+                    fail();
+                await assertNotRevoked();
+                return Object.freeze({ source_handle: alias.source_handle });
+            }
+            catch {
+                return fail();
+            }
+            finally {
+                versionSecret?.fill(0);
+                grantBytes?.fill(0);
+            }
+        }
+    });
+};

package/dist/auth/targetSecretSourceGrantRecords.d.ts

@@ -0,0 +1,84 @@
+import { type TargetSecretSourceAuthorization } from "../target/dockerSecretsAuthority.js";
+import { type SelectedTargetReceipt } from "../target/contracts.js";
+import { parseTargetSecretSourceOpaqueHandle } from "./targetSecretSourceRecordCommon.js";
+export declare const TARGET_SECRET_SOURCE_GRANT_RECORD_VERSION: "spawnfile.auth.target-secret.grant.v1";
+export declare const TARGET_SECRET_SOURCE_REDEMPTION_RECORD_VERSION: "spawnfile.auth.target-secret.redemption.v1";
+export declare const TARGET_SECRET_SOURCE_REVOCATION_RECORD_VERSION: "spawnfile.auth.target-secret.revocation.v1";
+export type TargetSecretSourceOpaqueHandle = ReturnType<typeof parseTargetSecretSourceOpaqueHandle>;
+export type TargetSecretSourceEntropy = () => Uint8Array;
+export type TargetSecretSourceGrantMetadata = Readonly<{
+    descriptor_digest: string;
+    name: string;
+    run_id: string;
+    scope: string;
+    selected_target: SelectedTargetReceipt;
+    source_handle: TargetSecretSourceOpaqueHandle;
+    source_version_handle: TargetSecretSourceOpaqueHandle;
+    version: typeof TARGET_SECRET_SOURCE_GRANT_RECORD_VERSION;
+}>;
+export type TargetSecretSourceGrantCommandInput = Readonly<Omit<TargetSecretSourceGrantMetadata, "source_version_handle" | "version">>;
+export type TargetSecretSourceGrantRecord = Readonly<TargetSecretSourceGrantMetadata & {
+    publication_handle: TargetSecretSourceOpaqueHandle;
+}>;
+export type TargetSecretSourceRedemptionMetadata = Readonly<{
+    authorization: TargetSecretSourceAuthorization;
+    source_handle: TargetSecretSourceOpaqueHandle;
+    source_version_handle: TargetSecretSourceOpaqueHandle;
+    version: typeof TARGET_SECRET_SOURCE_REDEMPTION_RECORD_VERSION;
+}>;
+export type TargetSecretSourceRedemptionRecord = Readonly<TargetSecretSourceRedemptionMetadata & {
+    publication_handle: TargetSecretSourceOpaqueHandle;
+}>;
+export type TargetSecretSourceRevocationMetadata = Readonly<{
+    kind: "grant" | "version";
+    revocation_handle: TargetSecretSourceOpaqueHandle;
+    revoked_handle: TargetSecretSourceOpaqueHandle;
+    version: typeof TARGET_SECRET_SOURCE_REVOCATION_RECORD_VERSION;
+}>;
+export type TargetSecretSourceRevocationRecord = Readonly<TargetSecretSourceRevocationMetadata & {
+    publication_handle: TargetSecretSourceOpaqueHandle;
+}>;
+export type TargetSecretSourceGrantRecordBytes = Uint8Array & {
+    readonly __brand: "TargetSecretSourceGrantRecordBytes";
+};
+export type TargetSecretSourceRedemptionRecordBytes = Uint8Array & {
+    readonly __brand: "TargetSecretSourceRedemptionRecordBytes";
+};
+export type TargetSecretSourceRevocationRecordBytes = Uint8Array & {
+    readonly __brand: "TargetSecretSourceRevocationRecordBytes";
+};
+export declare const parseTargetSecretSourceGrantCommandInput: (value: unknown) => TargetSecretSourceGrantCommandInput;
+export declare const createTargetSecretSourceGrantMetadata: (raw: unknown) => TargetSecretSourceGrantMetadata;
+export declare const createTargetSecretSourceGrantRecordBytes: (raw: unknown, options?: {
+    readonly publicationEntropy?: TargetSecretSourceEntropy;
+}) => {
+    readonly private_bytes: TargetSecretSourceGrantRecordBytes;
+    readonly private_metadata: TargetSecretSourceGrantRecord;
+    readonly metadata: TargetSecretSourceGrantMetadata;
+};
+export declare const parseTargetSecretSourceGrantRecordBytes: (raw: Uint8Array, expectedLeafHandle: TargetSecretSourceOpaqueHandle) => TargetSecretSourceGrantRecord;
+export declare const parseTargetSecretSourceGrantRecordBytesForPublication: (raw: Uint8Array) => TargetSecretSourceGrantRecord;
+export declare const createTargetSecretSourceRedemptionMetadata: (grant: TargetSecretSourceGrantMetadata, authorization: TargetSecretSourceAuthorization) => TargetSecretSourceRedemptionMetadata;
+export declare const createTargetSecretSourceRedemptionRecordBytes: (grant: TargetSecretSourceGrantMetadata, authorization: TargetSecretSourceAuthorization, options?: {
+    readonly publicationEntropy?: TargetSecretSourceEntropy;
+}) => {
+    readonly private_bytes: TargetSecretSourceRedemptionRecordBytes;
+    readonly private_metadata: TargetSecretSourceRedemptionRecord;
+    readonly metadata: TargetSecretSourceRedemptionMetadata;
+};
+export declare const parseTargetSecretSourceRedemptionRecordBytes: (raw: Uint8Array, expectedLeafHandle: TargetSecretSourceOpaqueHandle) => TargetSecretSourceRedemptionRecord;
+export declare const parseTargetSecretSourceRedemptionRecordBytesForPublication: (raw: Uint8Array) => TargetSecretSourceRedemptionRecord;
+export declare const assertTargetSecretSourceRedemptionCorrelation: (redemption: TargetSecretSourceRedemptionMetadata, grant: TargetSecretSourceGrantMetadata) => void;
+export declare const createTargetSecretSourceRevocationRecordBytes: (raw: {
+    readonly kind: "grant" | "version";
+    readonly revoked_handle: TargetSecretSourceOpaqueHandle;
+}, options?: {
+    readonly entropy?: TargetSecretSourceEntropy;
+    readonly publicationEntropy?: TargetSecretSourceEntropy;
+}) => {
+    readonly private_bytes: TargetSecretSourceRevocationRecordBytes;
+    readonly private_metadata: TargetSecretSourceRevocationRecord;
+    readonly metadata: TargetSecretSourceRevocationMetadata;
+};
+export declare const parseTargetSecretSourceRevocationRecordBytes: (raw: Uint8Array, expectedLeafHandle: TargetSecretSourceOpaqueHandle) => TargetSecretSourceRevocationRecord;
+export declare const parseTargetSecretSourceRevocationRecordBytesForPublication: (raw: Uint8Array) => TargetSecretSourceRevocationRecord;

package/dist/auth/targetSecretSourceGrantRecords.js

@@ -0,0 +1,214 @@
+import { Buffer } from "node:buffer";
+import { randomBytes } from "node:crypto";
+import { parseTargetSecretSourceAuthorization } from "../target/dockerSecretsAuthority.js";
+import { parseSelectedTargetReceipt } from "../target/contracts.js";
+import { TARGET_SECRET_SOURCE_ERROR, assertOrdinaryJsonGraph, createCanonicalTargetSecretSourceJson, parseCanonicalTargetSecretSourceJson, parseTargetSecretSourceOpaqueHandle } from "./targetSecretSourceRecordCommon.js";
+export const TARGET_SECRET_SOURCE_GRANT_RECORD_VERSION = "spawnfile.auth.target-secret.grant.v1";
+export const TARGET_SECRET_SOURCE_REDEMPTION_RECORD_VERSION = "spawnfile.auth.target-secret.redemption.v1";
+export const TARGET_SECRET_SOURCE_REVOCATION_RECORD_VERSION = "spawnfile.auth.target-secret.revocation.v1";
+const GRANT_KEYS = ["descriptor_digest", "name", "publication_handle", "run_id", "scope", "selected_target", "source_handle", "source_version_handle", "version"];
+const GRANT_METADATA_KEYS = GRANT_KEYS.filter((key) => key !== "publication_handle");
+const GRANT_INPUT_KEYS = GRANT_METADATA_KEYS.filter((key) => key !== "version");
+const GRANT_COMMAND_INPUT_KEYS = GRANT_INPUT_KEYS.filter((key) => key !== "source_version_handle");
+const REDEMPTION_KEYS = ["authorization", "publication_handle", "source_handle", "source_version_handle", "version"];
+const REDEMPTION_METADATA_KEYS = REDEMPTION_KEYS.filter((key) => key !== "publication_handle");
+const REVOCATION_KEYS = ["kind", "publication_handle", "revocation_handle", "revoked_handle", "version"];
+const REVOCATION_METADATA_KEYS = REVOCATION_KEYS.filter((key) => key !== "publication_handle");
+const PLACEHOLDER_HANDLE = "opaque_0000000000000000";
+const PLACEHOLDER_DIGEST = `sha256:${"0".repeat(64)}`;
+const fail = () => { throw new Error(TARGET_SECRET_SOURCE_ERROR); };
+const normalize = (work) => { try {
+    return work();
+}
+catch {
+    return fail();
+} };
+const freeze = (value) => Object.freeze(value);
+const defaultEntropy = () => {
+    const bytes = randomBytes(16);
+    try {
+        return Uint8Array.from(bytes);
+    }
+    finally {
+        bytes.fill(0);
+    }
+};
+const opaqueFromEntropy = (entropy) => normalize(() => {
+    const raw = entropy();
+    if (!(raw instanceof Uint8Array) || raw.length < 8 || raw.length > 32)
+        fail();
+    const copy = Uint8Array.from(raw);
+    const encoded = Buffer.from(copy);
+    try {
+        return parseTargetSecretSourceOpaqueHandle(`opaque_${encoded.toString("hex")}`);
+    }
+    finally {
+        encoded.fill(0);
+        copy.fill(0);
+    }
+});
+const exact = (value, keys) => {
+    assertOrdinaryJsonGraph(value);
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        fail();
+    const record = value;
+    const actual = Object.keys(record).sort();
+    if (actual.length !== keys.length || actual.some((key, index) => key !== keys[index]))
+        fail();
+    return record;
+};
+export const parseTargetSecretSourceGrantCommandInput = (value) => normalize(() => {
+    const record = exact(value, GRANT_COMMAND_INPUT_KEYS);
+    const selected = parseSelectedTargetReceipt(record.selected_target);
+    const sourceHandle = parseTargetSecretSourceOpaqueHandle(record.source_handle);
+    const authorization = parseTargetSecretSourceAuthorization({
+        descriptorDigest: record.descriptor_digest, name: record.name, operationHandle: PLACEHOLDER_HANDLE,
+        requestDigest: PLACEHOLDER_DIGEST, runId: record.run_id, scope: record.scope,
+        selectedTarget: { fingerprint: selected.fingerprint, handle: selected.handle }, sourceHandle,
+        version: "spawnfile.target-secret-source.authorization.v1"
+    });
+    if (sourceHandle === selected.handle)
+        fail();
+    return freeze({ descriptor_digest: authorization.descriptorDigest, name: authorization.name,
+        run_id: authorization.runId, scope: authorization.scope, selected_target: freeze({ ...selected }),
+        source_handle: sourceHandle });
+});
+const parseGrantMetadata = (value, expectedKeys = GRANT_METADATA_KEYS) => normalize(() => {
+    const record = exact(value, expectedKeys);
+    if (expectedKeys === GRANT_METADATA_KEYS && record.version !== TARGET_SECRET_SOURCE_GRANT_RECORD_VERSION)
+        fail();
+    const command = parseTargetSecretSourceGrantCommandInput(Object.fromEntries(GRANT_COMMAND_INPUT_KEYS.map((key) => [key, record[key]])));
+    const sourceVersionHandle = parseTargetSecretSourceOpaqueHandle(record.source_version_handle);
+    if (command.source_handle === sourceVersionHandle
+        || sourceVersionHandle === command.selected_target.handle)
+        fail();
+    return freeze({ ...command,
+        source_version_handle: sourceVersionHandle, version: TARGET_SECRET_SOURCE_GRANT_RECORD_VERSION });
+});
+const parseGrant = (value) => normalize(() => {
+    const record = exact(value, GRANT_KEYS);
+    const metadata = parseGrantMetadata(Object.fromEntries(GRANT_METADATA_KEYS.map((key) => [key, record[key]])));
+    const publicationHandle = parseTargetSecretSourceOpaqueHandle(record.publication_handle);
+    if (publicationHandle === metadata.source_handle || publicationHandle === metadata.source_version_handle
+        || publicationHandle === metadata.selected_target.handle)
+        fail();
+    return freeze({ publication_handle: publicationHandle, ...metadata });
+});
+const sameGrantAuthorization = (grant, authorization) => grant.descriptor_digest === authorization.descriptorDigest && grant.name === authorization.name && grant.run_id === authorization.runId
+    && grant.scope === authorization.scope && grant.source_handle === authorization.sourceHandle
+    && grant.selected_target.fingerprint === authorization.selectedTarget.fingerprint && grant.selected_target.handle === authorization.selectedTarget.handle;
+export const createTargetSecretSourceGrantMetadata = (raw) => normalize(() => parseGrantMetadata(raw, GRANT_INPUT_KEYS));
+const parseRedemptionMetadata = (value) => normalize(() => {
+    const record = exact(value, REDEMPTION_METADATA_KEYS);
+    if (record.version !== TARGET_SECRET_SOURCE_REDEMPTION_RECORD_VERSION)
+        fail();
+    const authorization = parseTargetSecretSourceAuthorization(record.authorization);
+    const sourceHandle = parseTargetSecretSourceOpaqueHandle(record.source_handle);
+    const sourceVersionHandle = parseTargetSecretSourceOpaqueHandle(record.source_version_handle);
+    if (new Set([
+        sourceHandle, sourceVersionHandle, authorization.operationHandle, authorization.selectedTarget.handle
+    ]).size !== 4)
+        fail();
+    return freeze({ authorization, source_handle: sourceHandle,
+        source_version_handle: sourceVersionHandle, version: TARGET_SECRET_SOURCE_REDEMPTION_RECORD_VERSION });
+});
+const parseRedemption = (value) => normalize(() => {
+    const record = exact(value, REDEMPTION_KEYS);
+    const metadata = parseRedemptionMetadata(Object.fromEntries(REDEMPTION_METADATA_KEYS.map((key) => [key, record[key]])));
+    const publicationHandle = parseTargetSecretSourceOpaqueHandle(record.publication_handle);
+    if (publicationHandle === metadata.source_handle || publicationHandle === metadata.source_version_handle
+        || publicationHandle === metadata.authorization.operationHandle
+        || publicationHandle === metadata.authorization.selectedTarget.handle)
+        fail();
+    return freeze({ publication_handle: publicationHandle, ...metadata });
+});
+const parseRevocationMetadata = (value) => normalize(() => {
+    const record = exact(value, REVOCATION_METADATA_KEYS);
+    if (record.version !== TARGET_SECRET_SOURCE_REVOCATION_RECORD_VERSION || (record.kind !== "grant" && record.kind !== "version"))
+        fail();
+    const revoked = parseTargetSecretSourceOpaqueHandle(record.revoked_handle);
+    const handle = parseTargetSecretSourceOpaqueHandle(record.revocation_handle);
+    if (revoked === handle)
+        fail();
+    return freeze({ kind: record.kind, revoked_handle: revoked, revocation_handle: handle, version: TARGET_SECRET_SOURCE_REVOCATION_RECORD_VERSION });
+});
+const parseRevocation = (value) => normalize(() => {
+    const record = exact(value, REVOCATION_KEYS);
+    const metadata = parseRevocationMetadata(Object.fromEntries(REVOCATION_METADATA_KEYS.map((key) => [key, record[key]])));
+    const publicationHandle = parseTargetSecretSourceOpaqueHandle(record.publication_handle);
+    if (publicationHandle === metadata.revoked_handle || publicationHandle === metadata.revocation_handle)
+        fail();
+    return freeze({ publication_handle: publicationHandle, ...metadata });
+});
+export const createTargetSecretSourceGrantRecordBytes = (raw, options = {}) => normalize(() => {
+    const input = createTargetSecretSourceGrantMetadata(raw);
+    const metadata = freeze(input);
+    const publicationHandle = opaqueFromEntropy(options.publicationEntropy ?? defaultEntropy);
+    if (publicationHandle === metadata.source_handle || publicationHandle === metadata.source_version_handle
+        || publicationHandle === metadata.selected_target.handle)
+        fail();
+    const privateMetadata = freeze({ publication_handle: publicationHandle, ...metadata });
+    return { private_bytes: createCanonicalTargetSecretSourceJson(privateMetadata), private_metadata: privateMetadata, metadata };
+});
+export const parseTargetSecretSourceGrantRecordBytes = (raw, expectedLeafHandle) => normalize(() => {
+    const expected = parseTargetSecretSourceOpaqueHandle(expectedLeafHandle);
+    const grant = parseTargetSecretSourceGrantRecordBytesForPublication(raw);
+    if (grant.source_handle !== expected)
+        fail();
+    return grant;
+});
+export const parseTargetSecretSourceGrantRecordBytesForPublication = (raw) => normalize(() => parseGrant(parseCanonicalTargetSecretSourceJson(raw)));
+export const createTargetSecretSourceRedemptionMetadata = (grant, authorization) => normalize(() => {
+    const parsedGrant = parseGrantMetadata(grant);
+    const parsedAuthorization = parseTargetSecretSourceAuthorization(authorization);
+    if (!sameGrantAuthorization(parsedGrant, parsedAuthorization))
+        fail();
+    return parseRedemptionMetadata({ authorization: parsedAuthorization, source_handle: parsedGrant.source_handle,
+        source_version_handle: parsedGrant.source_version_handle, version: TARGET_SECRET_SOURCE_REDEMPTION_RECORD_VERSION });
+});
+export const createTargetSecretSourceRedemptionRecordBytes = (grant, authorization, options = {}) => normalize(() => {
+    const metadata = createTargetSecretSourceRedemptionMetadata(grant, authorization);
+    const publicationHandle = opaqueFromEntropy(options.publicationEntropy ?? defaultEntropy);
+    if (publicationHandle === metadata.source_handle || publicationHandle === metadata.source_version_handle
+        || publicationHandle === metadata.authorization.operationHandle
+        || publicationHandle === metadata.authorization.selectedTarget.handle)
+        fail();
+    const privateMetadata = freeze({ publication_handle: publicationHandle, ...metadata });
+    return { private_bytes: createCanonicalTargetSecretSourceJson(privateMetadata), private_metadata: privateMetadata, metadata };
+});
+export const parseTargetSecretSourceRedemptionRecordBytes = (raw, expectedLeafHandle) => normalize(() => {
+    const expected = parseTargetSecretSourceOpaqueHandle(expectedLeafHandle);
+    const redemption = parseTargetSecretSourceRedemptionRecordBytesForPublication(raw);
+    if (redemption.source_handle !== expected)
+        fail();
+    return redemption;
+});
+export const parseTargetSecretSourceRedemptionRecordBytesForPublication = (raw) => normalize(() => parseRedemption(parseCanonicalTargetSecretSourceJson(raw)));
+export const assertTargetSecretSourceRedemptionCorrelation = (redemption, grant) => normalize(() => {
+    const parsedRedemption = parseRedemptionMetadata(redemption);
+    const parsedGrant = parseGrantMetadata(grant);
+    if (parsedRedemption.source_handle !== parsedGrant.source_handle || parsedRedemption.source_version_handle !== parsedGrant.source_version_handle
+        || !sameGrantAuthorization(parsedGrant, parsedRedemption.authorization))
+        fail();
+});
+export const createTargetSecretSourceRevocationRecordBytes = (raw, options = {}) => normalize(() => {
+    const input = exact(raw, ["kind", "revoked_handle"]);
+    if (input.kind !== "grant" && input.kind !== "version")
+        fail();
+    const revoked = parseTargetSecretSourceOpaqueHandle(input.revoked_handle);
+    const revocation = opaqueFromEntropy(options.entropy ?? defaultEntropy);
+    const publicationHandle = opaqueFromEntropy(options.publicationEntropy ?? defaultEntropy);
+    if (revoked === revocation || publicationHandle === revoked || publicationHandle === revocation)
+        fail();
+    const metadata = freeze({ kind: input.kind, revoked_handle: revoked, revocation_handle: revocation, version: TARGET_SECRET_SOURCE_REVOCATION_RECORD_VERSION });
+    const privateMetadata = freeze({ publication_handle: publicationHandle, ...metadata });
+    return { private_bytes: createCanonicalTargetSecretSourceJson(privateMetadata), private_metadata: privateMetadata, metadata };
+});
+export const parseTargetSecretSourceRevocationRecordBytes = (raw, expectedLeafHandle) => normalize(() => {
+    const expected = parseTargetSecretSourceOpaqueHandle(expectedLeafHandle);
+    const revocation = parseTargetSecretSourceRevocationRecordBytesForPublication(raw);
+    if (revocation.revoked_handle !== expected)
+        fail();
+    return revocation;
+});
+export const parseTargetSecretSourceRevocationRecordBytesForPublication = (raw) => normalize(() => parseRevocation(parseCanonicalTargetSecretSourceJson(raw)));

package/dist/auth/targetSecretSourceLifecycle.d.ts

@@ -0,0 +1,30 @@
+import type { TargetSecretSourceResolver } from "../target/dockerSecrets.js";
+import { type OpaqueTargetSecretSourceHandle } from "./targetSecretSourceRecordCommon.js";
+import { type TargetSecretSourceAuthor } from "./targetSecretSourceAuthor.js";
+import { type TargetSecretSourceGrant } from "./targetSecretSourceGrant.js";
+import { type TargetSecretSourceRevoke } from "./targetSecretSourceRevoke.js";
+import { type TargetSecretSourceRotate } from "./targetSecretSourceRotate.js";
+type SourceResult = Readonly<{
+    source_handle: OpaqueTargetSecretSourceHandle;
+}>;
+type RevokeResult = Readonly<{
+    kind: "grant" | "version";
+    source_handle: OpaqueTargetSecretSourceHandle;
+}>;
+export interface TargetSecretSourceLifecycle {
+    author(secret: Uint8Array): Promise<SourceResult>;
+    grant(input: unknown): Promise<SourceResult>;
+    resolver: TargetSecretSourceResolver;
+    revokeGrant(sourceHandle: unknown): Promise<RevokeResult>;
+    revokeVersion(sourceHandle: unknown): Promise<RevokeResult>;
+    rotate(sourceHandle: unknown, secret: Uint8Array): Promise<SourceResult>;
+}
+export interface TargetSecretSourceLifecycleOptions {
+    readonly author?: TargetSecretSourceAuthor;
+    readonly grant?: TargetSecretSourceGrant;
+    readonly resolver?: TargetSecretSourceResolver;
+    readonly revoke?: TargetSecretSourceRevoke;
+    readonly rotate?: TargetSecretSourceRotate;
+}
+export declare const initializeTargetSecretSourceLifecycle: (options?: TargetSecretSourceLifecycleOptions) => Promise<TargetSecretSourceLifecycle>;
+export {};

package/dist/auth/targetSecretSourceLifecycle.js

@@ -0,0 +1,52 @@
+import { TARGET_SECRET_SOURCE_ERROR, assertOrdinaryJsonGraph, parseTargetSecretSourceOpaqueHandle } from "./targetSecretSourceRecordCommon.js";
+import { initializeTargetSecretSourceAuthor } from "./targetSecretSourceAuthor.js";
+import { initializeTargetSecretSourceGrant } from "./targetSecretSourceGrant.js";
+import { parseTargetSecretSourceGrantCommandInput } from "./targetSecretSourceGrantRecords.js";
+import { initializeTargetSecretSourceResolver } from "./targetSecretSourceResolver.js";
+import { initializeTargetSecretSourceRevoke } from "./targetSecretSourceRevoke.js";
+import { initializeTargetSecretSourceRotate } from "./targetSecretSourceRotate.js";
+const fail = () => { throw new Error(TARGET_SECRET_SOURCE_ERROR); };
+const exact = (raw, keys) => {
+    assertOrdinaryJsonGraph(raw);
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return fail();
+    const record = raw;
+    const actual = Object.keys(record).sort();
+    if (actual.length !== keys.length || actual.some((key, index) => key !== keys[index]))
+        fail();
+    return record;
+};
+const projectSource = (raw) => {
+    const record = exact(raw, ["source_handle"]);
+    return Object.freeze({ source_handle: parseTargetSecretSourceOpaqueHandle(record.source_handle) });
+};
+const projectRevoke = (raw, kind) => {
+    const record = exact(raw, ["kind", "source_handle"]);
+    if (record.kind !== kind)
+        fail();
+    return Object.freeze({ kind, source_handle: parseTargetSecretSourceOpaqueHandle(record.source_handle) });
+};
+export const initializeTargetSecretSourceLifecycle = async (options = {}) => {
+    // Each default pins the same auth-owned hierarchy; initialize sequentially.
+    const author = options.author ?? await initializeTargetSecretSourceAuthor();
+    const grant = options.grant ?? await initializeTargetSecretSourceGrant();
+    const rotate = options.rotate ?? await initializeTargetSecretSourceRotate();
+    const revoke = options.revoke ?? await initializeTargetSecretSourceRevoke();
+    const resolver = options.resolver ?? await initializeTargetSecretSourceResolver();
+    return Object.freeze({
+        author: async (secret) => projectSource(await author.authorVersion(secret)),
+        grant: async (raw) => {
+            const input = parseTargetSecretSourceGrantCommandInput(raw);
+            const result = projectSource(await grant.grantSource(input));
+            if (result.source_handle !== input.source_handle)
+                fail();
+            return result;
+        },
+        resolver,
+        revokeGrant: async (sourceHandle) => projectRevoke(await revoke.revokeGrant(sourceHandle), "grant"),
+        revokeVersion: async (sourceHandle) => projectRevoke(await revoke.revokeVersion(sourceHandle), "version"),
+        rotate: async (sourceHandle, secret) => projectSource(await rotate.rotateSource({
+            secret, source_handle: sourceHandle
+        }))
+    });
+};

package/dist/auth/targetSecretSourceOwnerEntropy.d.ts

@@ -0,0 +1,6 @@
+export type TargetSecretSourceOwnerEntropyDomain = "grant.publication_handle" | "redemption.publication_handle" | "revocation.revocation_handle" | "revocation.publication_handle";
+/**
+ * Reconstructs lifecycle-record entropy solely from validated public semantics.
+ * The domain prefix prevents any handle role from sharing the same hash input.
+ */
+export declare const deriveTargetSecretSourceOwnerEntropy: (domain: TargetSecretSourceOwnerEntropyDomain, publicMetadata: unknown) => Uint8Array;

package/dist/auth/targetSecretSourceOwnerEntropy.js

@@ -0,0 +1,28 @@
+import { createHash } from "node:crypto";
+import { createCanonicalTargetSecretSourceJson, TARGET_SECRET_SOURCE_ERROR } from "./targetSecretSourceRecordCommon.js";
+const fail = () => { throw new Error(TARGET_SECRET_SOURCE_ERROR); };
+/**
+ * Reconstructs lifecycle-record entropy solely from validated public semantics.
+ * The domain prefix prevents any handle role from sharing the same hash input.
+ */
+export const deriveTargetSecretSourceOwnerEntropy = (domain, publicMetadata) => {
+    let canonical;
+    let digest;
+    try {
+        canonical = createCanonicalTargetSecretSourceJson(publicMetadata);
+        digest = createHash("sha256")
+            .update("spawnfile.auth.target-secret.owner-entropy.v1\0", "utf8")
+            .update(domain, "utf8")
+            .update("\0", "utf8")
+            .update(canonical)
+            .digest();
+        return Uint8Array.from(digest.subarray(0, 16));
+    }
+    catch {
+        return fail();
+    }
+    finally {
+        canonical?.fill(0);
+        digest?.fill(0);
+    }
+};

package/dist/auth/targetSecretSourceRecordCommon.d.ts

@@ -0,0 +1,14 @@
+import { parseOpaqueTargetHandle } from "../target/contracts.js";
+export declare const TARGET_SECRET_SOURCE_ERROR = "invalid target secret source record";
+export declare const MAX_TARGET_SECRET_SOURCE_SECRET_BYTES = 32768;
+export type OpaqueTargetSecretSourceHandle = ReturnType<typeof parseOpaqueTargetHandle>;
+export declare const MAX_JSON_GRAPH_DEPTH = 32;
+export declare const MAX_JSON_GRAPH_KEYS = 128;
+export declare const MAX_JSON_GRAPH_NODES = 1024;
+export declare const MAX_JSON_GRAPH_STRING_BYTES = 65536;
+export declare const assertOrdinaryJsonGraph: (raw: unknown) => void;
+export declare const parseCanonicalTargetSecretSourceJson: (raw: unknown) => unknown;
+export declare const createCanonicalTargetSecretSourceJson: (raw: unknown) => Uint8Array;
+export declare const parseTargetSecretSourceOpaqueHandle: (raw: unknown) => OpaqueTargetSecretSourceHandle;
+export declare const encodeTargetSecretSourceSecret: (raw: unknown) => string;
+export declare const decodeTargetSecretSourceSecret: (raw: unknown) => Uint8Array;

package/dist/auth/targetSecretSourceRecordCommon.js

@@ -0,0 +1,100 @@
+import { MAX_JSON_GRAPH_DEPTH as TARGET_MAX_JSON_GRAPH_DEPTH, MAX_JSON_GRAPH_KEYS as TARGET_MAX_JSON_GRAPH_KEYS, MAX_JSON_GRAPH_NODES as TARGET_MAX_JSON_GRAPH_NODES, MAX_JSON_GRAPH_STRING_BYTES as TARGET_MAX_JSON_GRAPH_STRING_BYTES, assertOrdinaryJsonGraph as assertTargetOrdinaryJsonGraph, parseOpaqueTargetHandle } from "../target/contracts.js";
+import { Buffer } from "node:buffer";
+const TEXT_ENCODER = new TextEncoder();
+const TEXT_DECODER = new TextDecoder("utf-8", { fatal: true });
+const BASE64_SECRET_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u;
+export const TARGET_SECRET_SOURCE_ERROR = "invalid target secret source record";
+export const MAX_TARGET_SECRET_SOURCE_SECRET_BYTES = 32_768;
+const MAX_ENCODED_SECRET_CHARACTERS = 4 * Math.ceil(MAX_TARGET_SECRET_SOURCE_SECRET_BYTES / 3);
+export const MAX_JSON_GRAPH_DEPTH = TARGET_MAX_JSON_GRAPH_DEPTH;
+export const MAX_JSON_GRAPH_KEYS = TARGET_MAX_JSON_GRAPH_KEYS;
+export const MAX_JSON_GRAPH_NODES = TARGET_MAX_JSON_GRAPH_NODES;
+export const MAX_JSON_GRAPH_STRING_BYTES = TARGET_MAX_JSON_GRAPH_STRING_BYTES;
+const fail = () => { throw new Error(TARGET_SECRET_SOURCE_ERROR); };
+const normalize = (work) => {
+    try {
+        return work();
+    }
+    catch {
+        return fail();
+    }
+};
+const compareCodeUnits = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const canonicalize = (value) => {
+    if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+        return value;
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (typeof value !== "object")
+        return fail();
+    const result = {};
+    for (const [key, nested] of Object.entries(value).sort(([a], [b]) => compareCodeUnits(a, b))) {
+        result[key] = canonicalize(nested);
+    }
+    return result;
+};
+const assertCanonicalBytes = (raw, text) => {
+    const canonical = TEXT_ENCODER.encode(text);
+    try {
+        if (canonical.length !== raw.length)
+            fail();
+        for (let index = 0; index < raw.length; index += 1)
+            if (canonical[index] !== raw[index])
+                fail();
+    }
+    finally {
+        canonical.fill(0);
+    }
+};
+export const assertOrdinaryJsonGraph = (raw) => normalize(() => {
+    assertTargetOrdinaryJsonGraph(raw);
+});
+export const parseCanonicalTargetSecretSourceJson = (raw) => normalize(() => {
+    if (!(raw instanceof Uint8Array) || raw.length > MAX_JSON_GRAPH_STRING_BYTES)
+        fail();
+    const bytes = raw;
+    const parsed = JSON.parse(TEXT_DECODER.decode(bytes));
+    assertTargetOrdinaryJsonGraph(parsed);
+    assertCanonicalBytes(bytes, JSON.stringify(canonicalize(parsed)));
+    return parsed;
+});
+export const createCanonicalTargetSecretSourceJson = (raw) => normalize(() => {
+    assertTargetOrdinaryJsonGraph(raw);
+    const encoded = TEXT_ENCODER.encode(JSON.stringify(canonicalize(raw)));
+    try {
+        if (encoded.length > MAX_JSON_GRAPH_STRING_BYTES)
+            fail();
+        return Uint8Array.from(encoded);
+    }
+    finally {
+        encoded.fill(0);
+    }
+});
+export const parseTargetSecretSourceOpaqueHandle = (raw) => normalize(() => parseOpaqueTargetHandle(raw));
+export const encodeTargetSecretSourceSecret = (raw) => normalize(() => {
+    if (!(raw instanceof Uint8Array) || raw.length === 0 || raw.length > MAX_TARGET_SECRET_SOURCE_SECRET_BYTES)
+        fail();
+    const copy = Uint8Array.from(raw);
+    const encoded = Buffer.from(copy);
+    try {
+        return encoded.toString("base64");
+    }
+    finally {
+        encoded.fill(0);
+        copy.fill(0);
+    }
+});
+export const decodeTargetSecretSourceSecret = (raw) => normalize(() => {
+    if (typeof raw !== "string" || raw.length > MAX_ENCODED_SECRET_CHARACTERS || !BASE64_SECRET_PATTERN.test(raw))
+        fail();
+    const encoded = raw;
+    const decoded = Buffer.from(encoded, "base64");
+    try {
+        if (decoded.toString("base64") !== encoded || decoded.length === 0 || decoded.length > MAX_TARGET_SECRET_SOURCE_SECRET_BYTES)
+            fail();
+        return Uint8Array.from(decoded);
+    }
+    finally {
+        decoded.fill(0);
+    }
+});

package/dist/auth/targetSecretSourceRecordPublish.d.ts

@@ -0,0 +1,10 @@
+import { type TargetSecretSourceFsPublishImmutableOptions } from "./targetSecretSourceFsPublishImmutable.js";
+export interface TargetSecretSourceRecordPublishOptions extends Pick<TargetSecretSourceFsPublishImmutableOptions, "hookForTest" | "maxWriteBytesForTest"> {
+}
+export interface TargetSecretSourceRecordPublish {
+    publishAlias(bytes: Uint8Array): Promise<void>;
+    publishGrant(bytes: Uint8Array): Promise<void>;
+    publishRedemption(bytes: Uint8Array): Promise<void>;
+    publishRevocation(bytes: Uint8Array): Promise<void>;
+}
+export declare const initializeTargetSecretSourceRecordPublish: (options?: TargetSecretSourceRecordPublishOptions) => Promise<TargetSecretSourceRecordPublish>;