@tearleads/client-sdk 0.0.0-stage → 0.1.13

package/internal/crypto/keying/principalPolicyHistoryTypes.d.ts

@@ -0,0 +1,46 @@
+import type { PrincipalPolicyExternalAuthority } from "./principalPolicyExternalAuthorityTypes.js";
+import type { PrincipalHistoryIndexNode } from "./principalPolicyHistoryIndex.js";
+import type { KeyingVerificationResult, PrincipalPolicyCheckpoint, PrincipalPolicySignerPublicKey, PrincipalPolicyStateChainEntry, ReferencedPrincipalHead } from "./types.js";
+export declare const PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT = 128;
+/** A crypto verification batch, not a wire-response DTO. */
+export interface PrincipalPolicyHistoryPage {
+    readonly entries: readonly PrincipalPolicyStateChainEntry[];
+    /** Keys resolved through the caller's trusted user-identity mechanism. */
+    readonly signerPublicKeys: readonly PrincipalPolicySignerPublicKey[];
+    /** Already authenticated authority; never trust a server page directly. */
+    readonly externalAuthority?: PrincipalPolicyExternalAuthority;
+}
+export interface PrincipalPolicyHistoryInput {
+    readonly principalId: string;
+    readonly principalType: ReferencedPrincipalHead["principalType"];
+    readonly localCheckpoint?: PrincipalPolicyCheckpoint | null;
+    readonly retainedReferences?: readonly ReferencedPrincipalHead[];
+}
+/** Local verifier protection; never obtain this key from a remote API. */
+export interface PrincipalPolicyHistoryProgressOptions {
+    readonly localKey: Uint8Array;
+    /** Stable local operation identity, bound into authenticated progress. */
+    readonly context: string;
+}
+declare const verifiedHistoryBrand: unique symbol;
+/** A verified prefix with explicitly retained references, not a full snapshot. */
+export interface VerifiedPrincipalPolicyHistory {
+    readonly [verifiedHistoryBrand]: true;
+    readonly currentEntry: PrincipalPolicyStateChainEntry;
+    readonly retainedEntries: readonly PrincipalPolicyStateChainEntry[];
+    readonly checkpoint: PrincipalPolicyCheckpoint;
+    /** Computed only from locally accepted entries; never supplied by a peer. */
+    readonly indexRootHash: string;
+}
+type HistorySnapshot = Omit<VerifiedPrincipalPolicyHistory, typeof verifiedHistoryBrand>;
+export declare function makeVerifiedPrincipalPolicyHistory(value: Omit<VerifiedPrincipalPolicyHistory, typeof verifiedHistoryBrand>): VerifiedPrincipalPolicyHistory;
+export declare function ownVerifiedPrincipalPolicyHistory(history: VerifiedPrincipalPolicyHistory): HistorySnapshot;
+export interface PrincipalPolicyHistoryVerifier {
+    append(page: PrincipalPolicyHistoryPage): Promise<KeyingVerificationResult<{
+        readonly throughVersion: number;
+        readonly indexNodes: readonly PrincipalHistoryIndexNode[];
+    }>>;
+    finish(expectedHead: ReferencedPrincipalHead): KeyingVerificationResult<VerifiedPrincipalPolicyHistory>;
+    exportProgress(options: PrincipalPolicyHistoryProgressOptions): Promise<KeyingVerificationResult<string>>;
+}
+export {};

package/internal/crypto/keying/principalPolicyHistoryTypes.js

@@ -0,0 +1,21 @@
+import { throwVerification } from "./shared.js";
+export const PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT = 128;
+const verifiedHistoryBrand = Symbol("verifiedPrincipalPolicyHistory");
+// Public copies are useful for inspection, but their fields are not authority.
+// A later verifier consumes the privately held snapshot issued by finish().
+const issuedHistories = new WeakMap();
+export function makeVerifiedPrincipalPolicyHistory(value) {
+    const result = {
+        ...value,
+        [verifiedHistoryBrand]: true,
+    };
+    issuedHistories.set(result, structuredClone(value));
+    return result;
+}
+export function ownVerifiedPrincipalPolicyHistory(history) {
+    const snapshot = issuedHistories.get(history);
+    if (!snapshot)
+        throwVerification("invalid_shape", "principal history must come from a local verifier");
+    return structuredClone(snapshot);
+}
+//# sourceMappingURL=principalPolicyHistoryTypes.js.map

package/internal/crypto/keying/principalPolicyHistoryTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalPolicyHistoryTypes.js","sourceRoot":"","sources":["principalPolicyHistoryTypes.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAS7C,MAAM,CAAC,MAAM,kCAAkC,GAAG,GAAG,CAAC;AAyBtD,MAAM,oBAAoB,GAAkB,MAAM,CAChD,gCAAgC,CACjC,CAAC;AAiBF,+EAA+E;AAC/E,4EAA4E;AAC5E,MAAM,eAAe,GAAG,IAAI,OAAO,EAGhC,CAAC;AAEJ,MAAM,UAAU,kCAAkC,CAChD,KAAwE;IAExE,MAAM,MAAM,GAAmC;QAC7C,GAAG,KAAK;QACR,CAAC,oBAAoB,CAAC,EAAE,IAAI;KAC7B,CAAC;IACF,eAAe,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC;IACpD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,iCAAiC,CAC/C,OAAuC;IAEvC,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC9C,IAAI,CAAC,QAAQ;QACX,iBAAiB,CACf,eAAe,EACf,mDAAmD,CACpD,CAAC;IACJ,OAAO,eAAe,CAAC,QAAQ,CAAC,CAAC;AACnC,CAAC","sourcesContent":["import type { PrincipalPolicyExternalAuthority } from \"./principalPolicyExternalAuthorityTypes\";\nimport type { PrincipalHistoryIndexNode } from \"./principalPolicyHistoryIndex\";\nimport { throwVerification } from \"./shared\";\nimport type {\n  KeyingVerificationResult,\n  PrincipalPolicyCheckpoint,\n  PrincipalPolicySignerPublicKey,\n  PrincipalPolicyStateChainEntry,\n  ReferencedPrincipalHead,\n} from \"./types\";\n\nexport const PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT = 128;\n\n/** A crypto verification batch, not a wire-response DTO. */\nexport interface PrincipalPolicyHistoryPage {\n  readonly entries: readonly PrincipalPolicyStateChainEntry[];\n  /** Keys resolved through the caller's trusted user-identity mechanism. */\n  readonly signerPublicKeys: readonly PrincipalPolicySignerPublicKey[];\n  /** Already authenticated authority; never trust a server page directly. */\n  readonly externalAuthority?: PrincipalPolicyExternalAuthority;\n}\n\nexport interface PrincipalPolicyHistoryInput {\n  readonly principalId: string;\n  readonly principalType: ReferencedPrincipalHead[\"principalType\"];\n  readonly localCheckpoint?: PrincipalPolicyCheckpoint | null;\n  readonly retainedReferences?: readonly ReferencedPrincipalHead[];\n}\n\n/** Local verifier protection; never obtain this key from a remote API. */\nexport interface PrincipalPolicyHistoryProgressOptions {\n  readonly localKey: Uint8Array;\n  /** Stable local operation identity, bound into authenticated progress. */\n  readonly context: string;\n}\n\nconst verifiedHistoryBrand: unique symbol = Symbol(\n  \"verifiedPrincipalPolicyHistory\",\n);\n\n/** A verified prefix with explicitly retained references, not a full snapshot. */\nexport interface VerifiedPrincipalPolicyHistory {\n  readonly [verifiedHistoryBrand]: true;\n  readonly currentEntry: PrincipalPolicyStateChainEntry;\n  readonly retainedEntries: readonly PrincipalPolicyStateChainEntry[];\n  readonly checkpoint: PrincipalPolicyCheckpoint;\n  /** Computed only from locally accepted entries; never supplied by a peer. */\n  readonly indexRootHash: string;\n}\n\ntype HistorySnapshot = Omit<\n  VerifiedPrincipalPolicyHistory,\n  typeof verifiedHistoryBrand\n>;\n\n// Public copies are useful for inspection, but their fields are not authority.\n// A later verifier consumes the privately held snapshot issued by finish().\nconst issuedHistories = new WeakMap<\n  VerifiedPrincipalPolicyHistory,\n  HistorySnapshot\n>();\n\nexport function makeVerifiedPrincipalPolicyHistory(\n  value: Omit<VerifiedPrincipalPolicyHistory, typeof verifiedHistoryBrand>,\n): VerifiedPrincipalPolicyHistory {\n  const result: VerifiedPrincipalPolicyHistory = {\n    ...value,\n    [verifiedHistoryBrand]: true,\n  };\n  issuedHistories.set(result, structuredClone(value));\n  return result;\n}\n\nexport function ownVerifiedPrincipalPolicyHistory(\n  history: VerifiedPrincipalPolicyHistory,\n): HistorySnapshot {\n  const snapshot = issuedHistories.get(history);\n  if (!snapshot)\n    throwVerification(\n      \"invalid_shape\",\n      \"principal history must come from a local verifier\",\n    );\n  return structuredClone(snapshot);\n}\n\nexport interface PrincipalPolicyHistoryVerifier {\n  append(page: PrincipalPolicyHistoryPage): Promise<\n    KeyingVerificationResult<{\n      readonly throughVersion: number;\n      readonly indexNodes: readonly PrincipalHistoryIndexNode[];\n    }>\n  >;\n  finish(\n    expectedHead: ReferencedPrincipalHead,\n  ): KeyingVerificationResult<VerifiedPrincipalPolicyHistory>;\n  exportProgress(\n    options: PrincipalPolicyHistoryProgressOptions,\n  ): Promise<KeyingVerificationResult<string>>;\n}\n"]}

package/internal/crypto/keying/principalPolicyMemberEnvelopes.js

@@ -0,0 +1,27 @@
+import { computePrincipalMemberEnvelopesRoot } from "../principalMemberEnvelopes.js";
+import { throwVerification } from "./shared.js";
+function memberKey(input) {
+    return input.userId;
+}
+export async function verifyPrincipalPolicyMemberEnvelopes(input) {
+    const { currentMemberEnvelopes, currentProjection, currentState } = input.bundle;
+    if (currentMemberEnvelopes.principalType !== currentState.principalType ||
+        currentMemberEnvelopes.principalId !== currentState.principalId) {
+        throwVerification("object_mismatch", "principal policy member envelopes do not match current state principal");
+    }
+    if (currentMemberEnvelopes.stateHash !== currentState.stateHash ||
+        currentMemberEnvelopes.epoch !== currentState.keyEpoch) {
+        throwVerification("hash_mismatch", "principal policy member envelopes do not match current state");
+    }
+    const computedRoot = await computePrincipalMemberEnvelopesRoot(currentMemberEnvelopes.envelopes);
+    if (computedRoot !== currentState.memberEnvelopesRoot) {
+        throwVerification("hash_mismatch", "principal policy member envelope root does not match current state");
+    }
+    const projectionMembers = new Set(currentProjection.map(memberKey));
+    const envelopeMembers = new Set(currentMemberEnvelopes.envelopes.map(memberKey));
+    if (projectionMembers.size !== envelopeMembers.size ||
+        [...projectionMembers].some((member) => !envelopeMembers.has(member))) {
+        throwVerification("hash_mismatch", "principal policy member envelopes do not match current projection");
+    }
+}
+//# sourceMappingURL=principalPolicyMemberEnvelopes.js.map

package/internal/crypto/keying/principalPolicyMemberEnvelopes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalPolicyMemberEnvelopes.js","sourceRoot":"","sources":["principalPolicyMemberEnvelopes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mCAAmC,EAAE,MAAM,6BAA6B,CAAC;AAClF,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAG7C,SAAS,SAAS,CAAC,KAAkC;IACnD,OAAO,KAAK,CAAC,MAAM,CAAC;AACtB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oCAAoC,CAAC,KAK1D;IACC,MAAM,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,YAAY,EAAE,GAC/D,KAAK,CAAC,MAAM,CAAC;IAEf,IACE,sBAAsB,CAAC,aAAa,KAAK,YAAY,CAAC,aAAa;QACnE,sBAAsB,CAAC,WAAW,KAAK,YAAY,CAAC,WAAW,EAC/D,CAAC;QACD,iBAAiB,CACf,iBAAiB,EACjB,wEAAwE,CACzE,CAAC;IACJ,CAAC;IAED,IACE,sBAAsB,CAAC,SAAS,KAAK,YAAY,CAAC,SAAS;QAC3D,sBAAsB,CAAC,KAAK,KAAK,YAAY,CAAC,QAAQ,EACtD,CAAC;QACD,iBAAiB,CACf,eAAe,EACf,8DAA8D,CAC/D,CAAC;IACJ,CAAC;IAED,MAAM,YAAY,GAAG,MAAM,mCAAmC,CAC5D,sBAAsB,CAAC,SAAS,CACjC,CAAC;IACF,IAAI,YAAY,KAAK,YAAY,CAAC,mBAAmB,EAAE,CAAC;QACtD,iBAAiB,CACf,eAAe,EACf,oEAAoE,CACrE,CAAC;IACJ,CAAC;IAED,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;IACpE,MAAM,eAAe,GAAG,IAAI,GAAG,CAC7B,sBAAsB,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAChD,CAAC;IACF,IACE,iBAAiB,CAAC,IAAI,KAAK,eAAe,CAAC,IAAI;QAC/C,CAAC,GAAG,iBAAiB,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,EACrE,CAAC;QACD,iBAAiB,CACf,eAAe,EACf,mEAAmE,CACpE,CAAC;IACJ,CAAC;AACH,CAAC","sourcesContent":["import { computePrincipalMemberEnvelopesRoot } from \"../principalMemberEnvelopes\";\nimport { throwVerification } from \"./shared\";\nimport type { PrincipalPolicyBundle } from \"./types\";\n\nfunction memberKey(input: { readonly userId: string }): string {\n  return input.userId;\n}\n\nexport async function verifyPrincipalPolicyMemberEnvelopes(input: {\n  readonly bundle: Pick<\n    PrincipalPolicyBundle,\n    \"currentState\" | \"currentProjection\" | \"currentMemberEnvelopes\"\n  >;\n}): Promise<void> {\n  const { currentMemberEnvelopes, currentProjection, currentState } =\n    input.bundle;\n\n  if (\n    currentMemberEnvelopes.principalType !== currentState.principalType ||\n    currentMemberEnvelopes.principalId !== currentState.principalId\n  ) {\n    throwVerification(\n      \"object_mismatch\",\n      \"principal policy member envelopes do not match current state principal\",\n    );\n  }\n\n  if (\n    currentMemberEnvelopes.stateHash !== currentState.stateHash ||\n    currentMemberEnvelopes.epoch !== currentState.keyEpoch\n  ) {\n    throwVerification(\n      \"hash_mismatch\",\n      \"principal policy member envelopes do not match current state\",\n    );\n  }\n\n  const computedRoot = await computePrincipalMemberEnvelopesRoot(\n    currentMemberEnvelopes.envelopes,\n  );\n  if (computedRoot !== currentState.memberEnvelopesRoot) {\n    throwVerification(\n      \"hash_mismatch\",\n      \"principal policy member envelope root does not match current state\",\n    );\n  }\n\n  const projectionMembers = new Set(currentProjection.map(memberKey));\n  const envelopeMembers = new Set(\n    currentMemberEnvelopes.envelopes.map(memberKey),\n  );\n  if (\n    projectionMembers.size !== envelopeMembers.size ||\n    [...projectionMembers].some((member) => !envelopeMembers.has(member))\n  ) {\n    throwVerification(\n      \"hash_mismatch\",\n      \"principal policy member envelopes do not match current projection\",\n    );\n  }\n}\n"]}

package/internal/crypto/keying/principalPolicyPayload.js

@@ -0,0 +1,20 @@
+import { computePrincipalStatePayloadCiphertextHash } from "../principalState.js";
+import { throwVerification } from "./shared.js";
+export async function verifyPrincipalPolicyPayload(input) {
+    const { currentPayload, currentState } = input.bundle;
+    if (currentPayload.principalType !== currentState.principalType ||
+        currentPayload.principalId !== currentState.principalId) {
+        throwVerification("object_mismatch", "principal policy payload does not match current state principal");
+    }
+    if (currentPayload.stateHash !== currentState.stateHash) {
+        throwVerification("hash_mismatch", "principal policy payload state hash does not match current state");
+    }
+    const computedPayloadHash = await computePrincipalStatePayloadCiphertextHash(currentPayload.ciphertext);
+    if (computedPayloadHash !== currentPayload.ciphertextHash) {
+        throwVerification("hash_mismatch", "principal policy payload hash does not match ciphertext");
+    }
+    if (computedPayloadHash !== currentState.payloadCiphertextHash) {
+        throwVerification("hash_mismatch", "principal policy payload hash does not match current state");
+    }
+}
+//# sourceMappingURL=principalPolicyPayload.js.map

package/internal/crypto/keying/principalPolicyPayload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalPolicyPayload.js","sourceRoot":"","sources":["principalPolicyPayload.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0CAA0C,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAG7C,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAAC,KAKlD;IACC,MAAM,EAAE,cAAc,EAAE,YAAY,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC;IAEtD,IACE,cAAc,CAAC,aAAa,KAAK,YAAY,CAAC,aAAa;QAC3D,cAAc,CAAC,WAAW,KAAK,YAAY,CAAC,WAAW,EACvD,CAAC;QACD,iBAAiB,CACf,iBAAiB,EACjB,iEAAiE,CAClE,CAAC;IACJ,CAAC;IAED,IAAI,cAAc,CAAC,SAAS,KAAK,YAAY,CAAC,SAAS,EAAE,CAAC;QACxD,iBAAiB,CACf,eAAe,EACf,kEAAkE,CACnE,CAAC;IACJ,CAAC;IAED,MAAM,mBAAmB,GAAG,MAAM,0CAA0C,CAC1E,cAAc,CAAC,UAAU,CAC1B,CAAC;IAEF,IAAI,mBAAmB,KAAK,cAAc,CAAC,cAAc,EAAE,CAAC;QAC1D,iBAAiB,CACf,eAAe,EACf,yDAAyD,CAC1D,CAAC;IACJ,CAAC;IAED,IAAI,mBAAmB,KAAK,YAAY,CAAC,qBAAqB,EAAE,CAAC;QAC/D,iBAAiB,CACf,eAAe,EACf,4DAA4D,CAC7D,CAAC;IACJ,CAAC;AACH,CAAC","sourcesContent":["import { computePrincipalStatePayloadCiphertextHash } from \"../principalState\";\nimport { throwVerification } from \"./shared\";\nimport type { PrincipalPolicyBundle } from \"./types\";\n\nexport async function verifyPrincipalPolicyPayload(input: {\n  readonly bundle: Pick<\n    PrincipalPolicyBundle,\n    \"currentState\" | \"currentPayload\"\n  >;\n}): Promise<void> {\n  const { currentPayload, currentState } = input.bundle;\n\n  if (\n    currentPayload.principalType !== currentState.principalType ||\n    currentPayload.principalId !== currentState.principalId\n  ) {\n    throwVerification(\n      \"object_mismatch\",\n      \"principal policy payload does not match current state principal\",\n    );\n  }\n\n  if (currentPayload.stateHash !== currentState.stateHash) {\n    throwVerification(\n      \"hash_mismatch\",\n      \"principal policy payload state hash does not match current state\",\n    );\n  }\n\n  const computedPayloadHash = await computePrincipalStatePayloadCiphertextHash(\n    currentPayload.ciphertext,\n  );\n\n  if (computedPayloadHash !== currentPayload.ciphertextHash) {\n    throwVerification(\n      \"hash_mismatch\",\n      \"principal policy payload hash does not match ciphertext\",\n    );\n  }\n\n  if (computedPayloadHash !== currentState.payloadCiphertextHash) {\n    throwVerification(\n      \"hash_mismatch\",\n      \"principal policy payload hash does not match current state\",\n    );\n  }\n}\n"]}

package/internal/crypto/keying/principalPolicyReference.js

@@ -0,0 +1,33 @@
+export function principalPolicyEntryForReference(input) {
+    const currentMatches = input.policy.principalType === input.reference.principalType &&
+        input.policy.principalId === input.reference.principalId &&
+        input.policy.version === input.reference.version &&
+        input.policy.keyEpoch === input.reference.keyEpoch &&
+        input.policy.stateHash === input.reference.stateHash &&
+        input.policy.state.keyFingerprint === input.reference.keyFingerprint;
+    if (currentMatches) {
+        return {
+            state: input.policy.state,
+            projection: input.policy.projection,
+            grants: input.policy.grants,
+        };
+    }
+    const history = "retainedHistory" in input.policy
+        ? input.policy.retainedHistory
+        : input.policy.history;
+    return history?.find((entry) => entry.state.principalType === input.reference.principalType &&
+        entry.state.principalId === input.reference.principalId &&
+        entry.state.version === input.reference.version &&
+        entry.state.keyEpoch === input.reference.keyEpoch &&
+        entry.state.stateHash === input.reference.stateHash &&
+        entry.state.keyFingerprint === input.reference.keyFingerprint);
+}
+export function principalPolicyStateMatchesReference(state, reference) {
+    return (state.principalId === reference.principalId &&
+        state.principalType === reference.principalType &&
+        state.version === reference.version &&
+        state.stateHash === reference.stateHash &&
+        state.keyEpoch === reference.keyEpoch &&
+        state.keyFingerprint === reference.keyFingerprint);
+}
+//# sourceMappingURL=principalPolicyReference.js.map

package/internal/crypto/keying/principalPolicyReference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalPolicyReference.js","sourceRoot":"","sources":["principalPolicyReference.ts"],"names":[],"mappings":"AAMA,MAAM,UAAU,gCAAgC,CAAC,KAGhD;IACC,MAAM,cAAc,GAClB,KAAK,CAAC,MAAM,CAAC,aAAa,KAAK,KAAK,CAAC,SAAS,CAAC,aAAa;QAC5D,KAAK,CAAC,MAAM,CAAC,WAAW,KAAK,KAAK,CAAC,SAAS,CAAC,WAAW;QACxD,KAAK,CAAC,MAAM,CAAC,OAAO,KAAK,KAAK,CAAC,SAAS,CAAC,OAAO;QAChD,KAAK,CAAC,MAAM,CAAC,QAAQ,KAAK,KAAK,CAAC,SAAS,CAAC,QAAQ;QAClD,KAAK,CAAC,MAAM,CAAC,SAAS,KAAK,KAAK,CAAC,SAAS,CAAC,SAAS;QACpD,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,KAAK,KAAK,CAAC,SAAS,CAAC,cAAc,CAAC;IACvE,IAAI,cAAc,EAAE,CAAC;QACnB,OAAO;YACL,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK;YACzB,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,UAAU;YACnC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM;SAC5B,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GACX,iBAAiB,IAAI,KAAK,CAAC,MAAM;QAC/B,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,eAAe;QAC9B,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC;IAC3B,OAAO,OAAO,EAAE,IAAI,CAClB,CAAC,KAAK,EAAE,EAAE,CACR,KAAK,CAAC,KAAK,CAAC,aAAa,KAAK,KAAK,CAAC,SAAS,CAAC,aAAa;QAC3D,KAAK,CAAC,KAAK,CAAC,WAAW,KAAK,KAAK,CAAC,SAAS,CAAC,WAAW;QACvD,KAAK,CAAC,KAAK,CAAC,OAAO,KAAK,KAAK,CAAC,SAAS,CAAC,OAAO;QAC/C,KAAK,CAAC,KAAK,CAAC,QAAQ,KAAK,KAAK,CAAC,SAAS,CAAC,QAAQ;QACjD,KAAK,CAAC,KAAK,CAAC,SAAS,KAAK,KAAK,CAAC,SAAS,CAAC,SAAS;QACnD,KAAK,CAAC,KAAK,CAAC,cAAc,KAAK,KAAK,CAAC,SAAS,CAAC,cAAc,CAChE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,oCAAoC,CAClD,KAA8B,EAC9B,SAAkC;IAElC,OAAO,CACL,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,WAAW;QAC3C,KAAK,CAAC,aAAa,KAAK,SAAS,CAAC,aAAa;QAC/C,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,OAAO;QACnC,KAAK,CAAC,SAAS,KAAK,SAAS,CAAC,SAAS;QACvC,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC,QAAQ;QACrC,KAAK,CAAC,cAAc,KAAK,SAAS,CAAC,cAAc,CAClD,CAAC;AACJ,CAAC","sourcesContent":["import type {\n  NormalizedPrincipalPolicyStateChainEntry,\n  PrincipalPolicyAuthorization,\n  ReferencedPrincipalHead,\n} from \"./types\";\n\nexport function principalPolicyEntryForReference(input: {\n  readonly policy: PrincipalPolicyAuthorization;\n  readonly reference: ReferencedPrincipalHead;\n}): NormalizedPrincipalPolicyStateChainEntry | undefined {\n  const currentMatches =\n    input.policy.principalType === input.reference.principalType &&\n    input.policy.principalId === input.reference.principalId &&\n    input.policy.version === input.reference.version &&\n    input.policy.keyEpoch === input.reference.keyEpoch &&\n    input.policy.stateHash === input.reference.stateHash &&\n    input.policy.state.keyFingerprint === input.reference.keyFingerprint;\n  if (currentMatches) {\n    return {\n      state: input.policy.state,\n      projection: input.policy.projection,\n      grants: input.policy.grants,\n    };\n  }\n  const history =\n    \"retainedHistory\" in input.policy\n      ? input.policy.retainedHistory\n      : input.policy.history;\n  return history?.find(\n    (entry) =>\n      entry.state.principalType === input.reference.principalType &&\n      entry.state.principalId === input.reference.principalId &&\n      entry.state.version === input.reference.version &&\n      entry.state.keyEpoch === input.reference.keyEpoch &&\n      entry.state.stateHash === input.reference.stateHash &&\n      entry.state.keyFingerprint === input.reference.keyFingerprint,\n  );\n}\n\nexport function principalPolicyStateMatchesReference(\n  state: ReferencedPrincipalHead,\n  reference: ReferencedPrincipalHead,\n): boolean {\n  return (\n    state.principalId === reference.principalId &&\n    state.principalType === reference.principalType &&\n    state.version === reference.version &&\n    state.stateHash === reference.stateHash &&\n    state.keyEpoch === reference.keyEpoch &&\n    state.keyFingerprint === reference.keyFingerprint\n  );\n}\n"]}

package/internal/crypto/keying/principalPolicySelection.d.ts

@@ -0,0 +1,11 @@
+import { type VerifiedPrincipalPolicyHistory } from "./principalPolicyHistoryTypes.js";
+import { type VerifiedPrincipalPolicySelection } from "./principalPolicyTypes.js";
+import type { KeyingVerificationResult } from "./types.js";
+export type { VerifiedPrincipalPolicySelection } from "./principalPolicyTypes.js";
+/**
+ * Public authorization evidence from a locally verified prefix. No payload or
+ * member envelopes are required, so a deleted principal remains verifiable.
+ * The result carries only selected entries and cannot stand in for full history
+ * or authenticated current keying artifacts.
+ */
+export declare function selectPrincipalPolicyAuthorization(verifiedHistory: VerifiedPrincipalPolicyHistory): Promise<KeyingVerificationResult<VerifiedPrincipalPolicySelection>>;

package/internal/crypto/keying/principalPolicySelection.js

@@ -0,0 +1,32 @@
+import { ownVerifiedPrincipalPolicyHistory, } from "./principalPolicyHistoryTypes.js";
+import { makeVerifiedPrincipalPolicySelection, } from "./principalPolicyTypes.js";
+import { runVerifier } from "./shared.js";
+/**
+ * Public authorization evidence from a locally verified prefix. No payload or
+ * member envelopes are required, so a deleted principal remains verifiable.
+ * The result carries only selected entries and cannot stand in for full history
+ * or authenticated current keying artifacts.
+ */
+export function selectPrincipalPolicyAuthorization(verifiedHistory) {
+    return runVerifier(async () => {
+        const history = ownVerifiedPrincipalPolicyHistory(verifiedHistory);
+        const { state, projection, grants } = history.currentEntry;
+        return makeVerifiedPrincipalPolicySelection({
+            principalType: state.principalType,
+            principalId: state.principalId,
+            version: state.version,
+            keyEpoch: state.keyEpoch,
+            stateHash: state.stateHash,
+            state,
+            projection: projection.map((member) => ({ ...member })),
+            grants: grants.map((grant) => ({ ...grant })),
+            checkpoint: history.checkpoint,
+            retainedHistory: history.retainedEntries.map((entry) => ({
+                state: entry.state,
+                projection: entry.projection.map((member) => ({ ...member })),
+                grants: entry.grants.map((grant) => ({ ...grant })),
+            })),
+        });
+    });
+}
+//# sourceMappingURL=principalPolicySelection.js.map

package/internal/crypto/keying/principalPolicySelection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalPolicySelection.js","sourceRoot":"","sources":["principalPolicySelection.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iCAAiC,GAElC,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,oCAAoC,GAErC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAKvC;;;;;GAKG;AACH,MAAM,UAAU,kCAAkC,CAChD,eAA+C;IAE/C,OAAO,WAAW,CAAC,KAAK,IAAI,EAAE;QAC5B,MAAM,OAAO,GAAG,iCAAiC,CAAC,eAAe,CAAC,CAAC;QACnE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC;QAC3D,OAAO,oCAAoC,CAAC;YAC1C,aAAa,EAAE,KAAK,CAAC,aAAa;YAClC,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,KAAK;YACL,UAAU,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;YACvD,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;YAC7C,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,eAAe,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBACvD,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;gBAC7D,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;aACpD,CAAC,CAAC;SACJ,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["import {\n  ownVerifiedPrincipalPolicyHistory,\n  type VerifiedPrincipalPolicyHistory,\n} from \"./principalPolicyHistoryTypes\";\nimport {\n  makeVerifiedPrincipalPolicySelection,\n  type VerifiedPrincipalPolicySelection,\n} from \"./principalPolicyTypes\";\nimport { runVerifier } from \"./shared\";\nimport type { KeyingVerificationResult } from \"./types\";\n\nexport type { VerifiedPrincipalPolicySelection } from \"./principalPolicyTypes\";\n\n/**\n * Public authorization evidence from a locally verified prefix. No payload or\n * member envelopes are required, so a deleted principal remains verifiable.\n * The result carries only selected entries and cannot stand in for full history\n * or authenticated current keying artifacts.\n */\nexport function selectPrincipalPolicyAuthorization(\n  verifiedHistory: VerifiedPrincipalPolicyHistory,\n): Promise<KeyingVerificationResult<VerifiedPrincipalPolicySelection>> {\n  return runVerifier(async () => {\n    const history = ownVerifiedPrincipalPolicyHistory(verifiedHistory);\n    const { state, projection, grants } = history.currentEntry;\n    return makeVerifiedPrincipalPolicySelection({\n      principalType: state.principalType,\n      principalId: state.principalId,\n      version: state.version,\n      keyEpoch: state.keyEpoch,\n      stateHash: state.stateHash,\n      state,\n      projection: projection.map((member) => ({ ...member })),\n      grants: grants.map((grant) => ({ ...grant })),\n      checkpoint: history.checkpoint,\n      retainedHistory: history.retainedEntries.map((entry) => ({\n        state: entry.state,\n        projection: entry.projection.map((member) => ({ ...member })),\n        grants: entry.grants.map((grant) => ({ ...grant })),\n      })),\n    });\n  });\n}\n"]}

package/internal/crypto/keying/principalPolicySignatures.js

@@ -0,0 +1,36 @@
+import { base64ToBytes } from "../../encoding/index.js";
+import { encodeUnsignedPrincipalState, normalizeUnsignedPrincipalState, toUnsignedPrincipalState, } from "../principalState.js";
+import { verifyHistorySignature } from "../signing/verifiedHistorySignature.js";
+import { createSignatureHistoryVerifier } from "../signing/verifiedSignatureHistory.js";
+import { throwVerification } from "./shared.js";
+const verifyHistory = createSignatureHistoryVerifier();
+export async function verifyPrincipalPolicyChainSignatures(input) {
+    const valid = await verifyHistory(async function* () {
+        for (const { state } of input.chain) {
+            const publicKey = input.signerPublicKeyByUserAndFingerprint.get(`${state.signerUserId}:${state.signerUserKeyFingerprint}`);
+            if (!publicKey)
+                throwVerification("missing_dependency", "principal policy signer public key is unavailable");
+            const normalized = await normalizeUnsignedPrincipalState(toUnsignedPrincipalState(state));
+            let signature;
+            try {
+                signature = base64ToBytes(state.signature);
+            }
+            catch {
+                throwVerification("signature_mismatch", "principal policy state signature verification failed");
+            }
+            yield {
+                signature,
+                message: encodeUnsignedPrincipalState(normalized),
+                publicKey,
+            };
+        }
+    });
+    if (!valid)
+        throwVerification("signature_mismatch", "principal policy state signature verification failed");
+}
+/** Test fixture for complete loss of volatile signature mathematics caches. */
+export function clearPrincipalPolicySignatureCaches() {
+    verifyHistory.clear();
+    verifyHistorySignature.clear();
+}
+//# sourceMappingURL=principalPolicySignatures.js.map

package/internal/crypto/keying/principalPolicySignatures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalPolicySignatures.js","sourceRoot":"","sources":["principalPolicySignatures.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACL,4BAA4B,EAC5B,+BAA+B,EAC/B,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,EAAE,8BAA8B,EAAE,MAAM,qCAAqC,CAAC;AACrF,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAG7C,MAAM,aAAa,GAAG,8BAA8B,EAAE,CAAC;AAEvD,MAAM,CAAC,KAAK,UAAU,oCAAoC,CAAC,KAG1D;IACC,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,KAAK,SAAS,CAAC;QAC/C,KAAK,MAAM,EAAE,KAAK,EAAE,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YACpC,MAAM,SAAS,GAAG,KAAK,CAAC,mCAAmC,CAAC,GAAG,CAC7D,GAAG,KAAK,CAAC,YAAY,IAAI,KAAK,CAAC,wBAAwB,EAAE,CAC1D,CAAC;YACF,IAAI,CAAC,SAAS;gBACZ,iBAAiB,CACf,oBAAoB,EACpB,mDAAmD,CACpD,CAAC;YACJ,MAAM,UAAU,GAAG,MAAM,+BAA+B,CACtD,wBAAwB,CAAC,KAAK,CAAC,CAChC,CAAC;YACF,IAAI,SAAqB,CAAC;YAC1B,IAAI,CAAC;gBACH,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YAC7C,CAAC;YAAC,MAAM,CAAC;gBACP,iBAAiB,CACf,oBAAoB,EACpB,sDAAsD,CACvD,CAAC;YACJ,CAAC;YACD,MAAM;gBACJ,SAAS;gBACT,OAAO,EAAE,4BAA4B,CAAC,UAAU,CAAC;gBACjD,SAAS;aACV,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CAAC;IACH,IAAI,CAAC,KAAK;QACR,iBAAiB,CACf,oBAAoB,EACpB,sDAAsD,CACvD,CAAC;AACN,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,mCAAmC;IACjD,aAAa,CAAC,KAAK,EAAE,CAAC;IACtB,sBAAsB,CAAC,KAAK,EAAE,CAAC;AACjC,CAAC","sourcesContent":["import { base64ToBytes } from \"@tearleads/encoding\";\nimport {\n  encodeUnsignedPrincipalState,\n  normalizeUnsignedPrincipalState,\n  toUnsignedPrincipalState,\n} from \"../principalState\";\nimport { verifyHistorySignature } from \"../signing/verifiedHistorySignature\";\nimport { createSignatureHistoryVerifier } from \"../signing/verifiedSignatureHistory\";\nimport { throwVerification } from \"./shared\";\nimport type { NormalizedPrincipalPolicyStateChainEntry } from \"./types\";\n\nconst verifyHistory = createSignatureHistoryVerifier();\n\nexport async function verifyPrincipalPolicyChainSignatures(input: {\n  readonly chain: readonly NormalizedPrincipalPolicyStateChainEntry[];\n  readonly signerPublicKeyByUserAndFingerprint: ReadonlyMap<string, Uint8Array>;\n}): Promise<void> {\n  const valid = await verifyHistory(async function* () {\n    for (const { state } of input.chain) {\n      const publicKey = input.signerPublicKeyByUserAndFingerprint.get(\n        `${state.signerUserId}:${state.signerUserKeyFingerprint}`,\n      );\n      if (!publicKey)\n        throwVerification(\n          \"missing_dependency\",\n          \"principal policy signer public key is unavailable\",\n        );\n      const normalized = await normalizeUnsignedPrincipalState(\n        toUnsignedPrincipalState(state),\n      );\n      let signature: Uint8Array;\n      try {\n        signature = base64ToBytes(state.signature);\n      } catch {\n        throwVerification(\n          \"signature_mismatch\",\n          \"principal policy state signature verification failed\",\n        );\n      }\n      yield {\n        signature,\n        message: encodeUnsignedPrincipalState(normalized),\n        publicKey,\n      };\n    }\n  });\n  if (!valid)\n    throwVerification(\n      \"signature_mismatch\",\n      \"principal policy state signature verification failed\",\n    );\n}\n\n/** Test fixture for complete loss of volatile signature mathematics caches. */\nexport function clearPrincipalPolicySignatureCaches(): void {\n  verifyHistory.clear();\n  verifyHistorySignature.clear();\n}\n"]}

package/internal/crypto/keying/principalPolicySignerKeys.js

@@ -0,0 +1,30 @@
+import { toFingerprint } from "../fingerprint.js";
+import { throwVerification } from "./shared.js";
+function normalizePrincipalPolicySignerKey(signerKey) {
+    if (signerKey.userId.length === 0) {
+        throwVerification("invalid_shape", "principal policy signer user missing");
+    }
+    if (!/^[0-9a-f]{64}$/.test(signerKey.signingKeyFingerprint)) {
+        throwVerification("hash_mismatch", "principal policy signer fingerprint must be a 64-character lowercase hex hash");
+    }
+    if (signerKey.signingPublicKey.length === 0) {
+        throwVerification("invalid_shape", "principal policy signer public key missing");
+    }
+    return signerKey;
+}
+export async function buildPrincipalPolicySignerKeyMap(signerPublicKeys) {
+    const signerPublicKeyByUserAndFingerprint = new Map();
+    for (const signerKey of signerPublicKeys.map(normalizePrincipalPolicySignerKey)) {
+        const computedFingerprint = await toFingerprint(signerKey.signingPublicKey);
+        if (computedFingerprint !== signerKey.signingKeyFingerprint) {
+            throwVerification("signer_mismatch", "principal policy signer key fingerprint does not match public key");
+        }
+        const key = `${signerKey.userId}:${signerKey.signingKeyFingerprint}`;
+        if (signerPublicKeyByUserAndFingerprint.has(key)) {
+            throwVerification("duplicate_entry", "principal policy signer key list contains a duplicate");
+        }
+        signerPublicKeyByUserAndFingerprint.set(key, signerKey.signingPublicKey);
+    }
+    return signerPublicKeyByUserAndFingerprint;
+}
+//# sourceMappingURL=principalPolicySignerKeys.js.map

package/internal/crypto/keying/principalPolicySignerKeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalPolicySignerKeys.js","sourceRoot":"","sources":["principalPolicySignerKeys.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAG7C,SAAS,iCAAiC,CACxC,SAAyC;IAEzC,IAAI,SAAS,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClC,iBAAiB,CAAC,eAAe,EAAE,sCAAsC,CAAC,CAAC;IAC7E,CAAC;IAED,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,qBAAqB,CAAC,EAAE,CAAC;QAC5D,iBAAiB,CACf,eAAe,EACf,+EAA+E,CAChF,CAAC;IACJ,CAAC;IAED,IAAI,SAAS,CAAC,gBAAgB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5C,iBAAiB,CACf,eAAe,EACf,4CAA4C,CAC7C,CAAC;IACJ,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gCAAgC,CACpD,gBAA2D;IAE3D,MAAM,mCAAmC,GAAG,IAAI,GAAG,EAAsB,CAAC;IAE1E,KAAK,MAAM,SAAS,IAAI,gBAAgB,CAAC,GAAG,CAC1C,iCAAiC,CAClC,EAAE,CAAC;QACF,MAAM,mBAAmB,GAAG,MAAM,aAAa,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;QAE5E,IAAI,mBAAmB,KAAK,SAAS,CAAC,qBAAqB,EAAE,CAAC;YAC5D,iBAAiB,CACf,iBAAiB,EACjB,mEAAmE,CACpE,CAAC;QACJ,CAAC;QAED,MAAM,GAAG,GAAG,GAAG,SAAS,CAAC,MAAM,IAAI,SAAS,CAAC,qBAAqB,EAAE,CAAC;QACrE,IAAI,mCAAmC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACjD,iBAAiB,CACf,iBAAiB,EACjB,uDAAuD,CACxD,CAAC;QACJ,CAAC;QAED,mCAAmC,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,gBAAgB,CAAC,CAAC;IAC3E,CAAC;IAED,OAAO,mCAAmC,CAAC;AAC7C,CAAC","sourcesContent":["import { toFingerprint } from \"../fingerprint\";\nimport { throwVerification } from \"./shared\";\nimport type { PrincipalPolicySignerPublicKey } from \"./types\";\n\nfunction normalizePrincipalPolicySignerKey(\n  signerKey: PrincipalPolicySignerPublicKey,\n): PrincipalPolicySignerPublicKey {\n  if (signerKey.userId.length === 0) {\n    throwVerification(\"invalid_shape\", \"principal policy signer user missing\");\n  }\n\n  if (!/^[0-9a-f]{64}$/.test(signerKey.signingKeyFingerprint)) {\n    throwVerification(\n      \"hash_mismatch\",\n      \"principal policy signer fingerprint must be a 64-character lowercase hex hash\",\n    );\n  }\n\n  if (signerKey.signingPublicKey.length === 0) {\n    throwVerification(\n      \"invalid_shape\",\n      \"principal policy signer public key missing\",\n    );\n  }\n\n  return signerKey;\n}\n\nexport async function buildPrincipalPolicySignerKeyMap(\n  signerPublicKeys: readonly PrincipalPolicySignerPublicKey[],\n): Promise<Map<string, Uint8Array>> {\n  const signerPublicKeyByUserAndFingerprint = new Map<string, Uint8Array>();\n\n  for (const signerKey of signerPublicKeys.map(\n    normalizePrincipalPolicySignerKey,\n  )) {\n    const computedFingerprint = await toFingerprint(signerKey.signingPublicKey);\n\n    if (computedFingerprint !== signerKey.signingKeyFingerprint) {\n      throwVerification(\n        \"signer_mismatch\",\n        \"principal policy signer key fingerprint does not match public key\",\n      );\n    }\n\n    const key = `${signerKey.userId}:${signerKey.signingKeyFingerprint}`;\n    if (signerPublicKeyByUserAndFingerprint.has(key)) {\n      throwVerification(\n        \"duplicate_entry\",\n        \"principal policy signer key list contains a duplicate\",\n      );\n    }\n\n    signerPublicKeyByUserAndFingerprint.set(key, signerKey.signingPublicKey);\n  }\n\n  return signerPublicKeyByUserAndFingerprint;\n}\n"]}

package/internal/crypto/keying/principalPolicyTransition.d.ts

@@ -0,0 +1,21 @@
+import type { PrincipalContainerGrant, PrincipalProjectionMember, SignedPrincipalState } from "../principalState.js";
+import type { PrincipalPolicySignedState } from "./types.js";
+export type PrincipalPolicyTransitionMismatchCode = "epoch_advance_without_key_material" | "grant_removal_without_key_rotation" | "key_change_without_epoch" | "key_epoch_decrease" | "previous_hash_mismatch" | "principal_mismatch" | "shrink_without_key_rotation" | "version_not_contiguous";
+export interface PrincipalPolicyTransitionMismatch {
+    readonly code: PrincipalPolicyTransitionMismatchCode;
+    readonly message: string;
+}
+export declare function getPrincipalPolicyTransitionMismatch(input: {
+    readonly current: {
+        readonly grants: readonly PrincipalContainerGrant[];
+        readonly projection: readonly PrincipalProjectionMember[];
+        readonly state: SignedPrincipalState;
+    };
+    readonly previous: {
+        readonly grants: readonly PrincipalContainerGrant[];
+        readonly projection: readonly PrincipalProjectionMember[];
+        readonly state: PrincipalPolicySignedState;
+    };
+}): PrincipalPolicyTransitionMismatch | null;
+export declare function getPrincipalPolicyTransitionMismatchReason(input: Parameters<typeof getPrincipalPolicyTransitionMismatch>[0]): string | null;
+export declare function throwPrincipalPolicyTransitionError(mismatch: PrincipalPolicyTransitionMismatch): never;

package/internal/crypto/keying/principalPolicyTransition.js

@@ -0,0 +1,103 @@
+import { normalizePrincipalProjectionMembers } from "../principalState.js";
+import { throwVerification } from "./shared.js";
+function principalProjectionMemberKey(member) {
+    return member.userId;
+}
+function principalProjectionRoleRank(role) {
+    return role === "admin" ? 2 : 1;
+}
+function hasPrincipalPolicyProjectionShrink(input) {
+    const currentProjectionByMember = new Map(input.currentProjection.map((member) => [
+        principalProjectionMemberKey(member),
+        member,
+    ]));
+    return input.previousProjection.some((previousMember) => {
+        const currentMember = currentProjectionByMember.get(principalProjectionMemberKey(previousMember));
+        if (!currentMember) {
+            return true;
+        }
+        return (principalProjectionRoleRank(currentMember.role) <
+            principalProjectionRoleRank(previousMember.role));
+    });
+}
+/**
+ * Container KEK wraps sealed to a group's key stay stored after the group
+ * loses a grant, so a member added later at the same key epoch could still
+ * open them (#2365 finding 20). A grant may change its access level in place,
+ * but dropping a container needs a new key, exactly like a projection shrink.
+ */
+function hasPrincipalPolicyGrantRemoval(input) {
+    const retained = new Set(input.currentGrants.map((grant) => grant.containerId));
+    return input.previousGrants.some((grant) => !retained.has(grant.containerId));
+}
+function principalPolicyKeyMaterialChanged(input) {
+    return (input.currentState.encapsulationPublicKey !==
+        input.previousState.encapsulationPublicKey ||
+        input.currentState.keyFingerprint !== input.previousState.keyFingerprint);
+}
+function principalPolicyTransitionMismatch(code, message) {
+    return { code, message };
+}
+export function getPrincipalPolicyTransitionMismatch(input) {
+    const { current, previous } = input;
+    if (current.state.principalType !== previous.state.principalType ||
+        current.state.principalId !== previous.state.principalId) {
+        return principalPolicyTransitionMismatch("principal_mismatch", "Principal policy transition principal mismatch");
+    }
+    if (current.state.version !== previous.state.version + 1) {
+        return principalPolicyTransitionMismatch("version_not_contiguous", "Principal policy transition version is not contiguous");
+    }
+    if (current.state.prevStateHash !== previous.state.stateHash) {
+        return principalPolicyTransitionMismatch("previous_hash_mismatch", "Principal policy transition previous hash mismatch");
+    }
+    if (current.state.keyEpoch < previous.state.keyEpoch) {
+        return principalPolicyTransitionMismatch("key_epoch_decrease", "Principal policy key epoch cannot decrease");
+    }
+    const previousProjection = normalizePrincipalProjectionMembers(previous.projection);
+    const currentProjection = normalizePrincipalProjectionMembers(current.projection);
+    const keyMaterialChanged = principalPolicyKeyMaterialChanged({
+        currentState: current.state,
+        previousState: previous.state,
+    });
+    if (current.state.keyEpoch === previous.state.keyEpoch &&
+        keyMaterialChanged) {
+        return principalPolicyTransitionMismatch("key_change_without_epoch", "Principal policy key change requires a new key epoch");
+    }
+    if (current.state.keyEpoch > previous.state.keyEpoch && !keyMaterialChanged) {
+        return principalPolicyTransitionMismatch("epoch_advance_without_key_material", "Principal policy key epoch advance requires new key material");
+    }
+    if (hasPrincipalPolicyProjectionShrink({
+        currentProjection,
+        previousProjection,
+    }) &&
+        (current.state.keyEpoch <= previous.state.keyEpoch || !keyMaterialChanged)) {
+        return principalPolicyTransitionMismatch("shrink_without_key_rotation", "Principal policy shrink requires a new key epoch and key material");
+    }
+    if (hasPrincipalPolicyGrantRemoval({
+        currentGrants: current.grants,
+        previousGrants: previous.grants,
+    }) &&
+        current.state.keyEpoch <= previous.state.keyEpoch) {
+        return principalPolicyTransitionMismatch("grant_removal_without_key_rotation", "Principal policy grant removal requires a new key epoch");
+    }
+    return null;
+}
+export function getPrincipalPolicyTransitionMismatchReason(input) {
+    return getPrincipalPolicyTransitionMismatch(input)?.message ?? null;
+}
+export function throwPrincipalPolicyTransitionError(mismatch) {
+    switch (mismatch.code) {
+        case "epoch_advance_without_key_material":
+        case "grant_removal_without_key_rotation":
+        case "key_change_without_epoch":
+        case "key_epoch_decrease":
+        case "shrink_without_key_rotation":
+            return throwVerification("key_epoch_reuse", mismatch.message);
+        case "previous_hash_mismatch":
+            return throwVerification("stale_predecessor", mismatch.message);
+        case "principal_mismatch":
+        case "version_not_contiguous":
+            return throwVerification("invalid_shape", mismatch.message);
+    }
+}
+//# sourceMappingURL=principalPolicyTransition.js.map

package/internal/crypto/keying/principalPolicyTransition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalPolicyTransition.js","sourceRoot":"","sources":["principalPolicyTransition.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  PrincipalContainerGrant,\n  PrincipalProjectionMember,\n  SignedPrincipalState,\n} from \"../principalState\";\nimport { normalizePrincipalProjectionMembers } from \"../principalState\";\nimport { throwVerification } from \"./shared\";\nimport type { PrincipalPolicySignedState } from \"./types\";\n\nfunction principalProjectionMemberKey(\n  member: PrincipalProjectionMember,\n): string {\n  return member.userId;\n}\n\nfunction principalProjectionRoleRank(\n  role: PrincipalProjectionMember[\"role\"],\n): number {\n  return role === \"admin\" ? 2 : 1;\n}\n\nfunction hasPrincipalPolicyProjectionShrink(input: {\n  currentProjection: readonly PrincipalProjectionMember[];\n  previousProjection: readonly PrincipalProjectionMember[];\n}): boolean {\n  const currentProjectionByMember = new Map<string, PrincipalProjectionMember>(\n    input.currentProjection.map((member) => [\n      principalProjectionMemberKey(member),\n      member,\n    ]),\n  );\n\n  return input.previousProjection.some((previousMember) => {\n    const currentMember = currentProjectionByMember.get(\n      principalProjectionMemberKey(previousMember),\n    );\n\n    if (!currentMember) {\n      return true;\n    }\n\n    return (\n      principalProjectionRoleRank(currentMember.role) <\n      principalProjectionRoleRank(previousMember.role)\n    );\n  });\n}\n\n/**\n * Container KEK wraps sealed to a group's key stay stored after the group\n * loses a grant, so a member added later at the same key epoch could still\n * open them (#2365 finding 20). A grant may change its access level in place,\n * but dropping a container needs a new key, exactly like a projection shrink.\n */\nfunction hasPrincipalPolicyGrantRemoval(input: {\n  currentGrants: readonly PrincipalContainerGrant[];\n  previousGrants: readonly PrincipalContainerGrant[];\n}): boolean {\n  const retained = new Set(\n    input.currentGrants.map((grant) => grant.containerId),\n  );\n  return input.previousGrants.some((grant) => !retained.has(grant.containerId));\n}\n\nfunction principalPolicyKeyMaterialChanged(input: {\n  currentState: SignedPrincipalState;\n  previousState: SignedPrincipalState;\n}): boolean {\n  return (\n    input.currentState.encapsulationPublicKey !==\n      input.previousState.encapsulationPublicKey ||\n    input.currentState.keyFingerprint !== input.previousState.keyFingerprint\n  );\n}\n\nexport type PrincipalPolicyTransitionMismatchCode =\n  | \"epoch_advance_without_key_material\"\n  | \"grant_removal_without_key_rotation\"\n  | \"key_change_without_epoch\"\n  | \"key_epoch_decrease\"\n  | \"previous_hash_mismatch\"\n  | \"principal_mismatch\"\n  | \"shrink_without_key_rotation\"\n  | \"version_not_contiguous\";\n\nexport interface PrincipalPolicyTransitionMismatch {\n  readonly code: PrincipalPolicyTransitionMismatchCode;\n  readonly message: string;\n}\n\nfunction principalPolicyTransitionMismatch(\n  code: PrincipalPolicyTransitionMismatchCode,\n  message: string,\n): PrincipalPolicyTransitionMismatch {\n  return { code, message };\n}\n\nexport function getPrincipalPolicyTransitionMismatch(input: {\n  readonly current: {\n    readonly grants: readonly PrincipalContainerGrant[];\n    readonly projection: readonly PrincipalProjectionMember[];\n    readonly state: SignedPrincipalState;\n  };\n  readonly previous: {\n    readonly grants: readonly PrincipalContainerGrant[];\n    readonly projection: readonly PrincipalProjectionMember[];\n    readonly state: PrincipalPolicySignedState;\n  };\n}): PrincipalPolicyTransitionMismatch | null {\n  const { current, previous } = input;\n\n  if (\n    current.state.principalType !== previous.state.principalType ||\n    current.state.principalId !== previous.state.principalId\n  ) {\n    return principalPolicyTransitionMismatch(\n      \"principal_mismatch\",\n      \"Principal policy transition principal mismatch\",\n    );\n  }\n\n  if (current.state.version !== previous.state.version + 1) {\n    return principalPolicyTransitionMismatch(\n      \"version_not_contiguous\",\n      \"Principal policy transition version is not contiguous\",\n    );\n  }\n\n  if (current.state.prevStateHash !== previous.state.stateHash) {\n    return principalPolicyTransitionMismatch(\n      \"previous_hash_mismatch\",\n      \"Principal policy transition previous hash mismatch\",\n    );\n  }\n\n  if (current.state.keyEpoch < previous.state.keyEpoch) {\n    return principalPolicyTransitionMismatch(\n      \"key_epoch_decrease\",\n      \"Principal policy key epoch cannot decrease\",\n    );\n  }\n\n  const previousProjection = normalizePrincipalProjectionMembers(\n    previous.projection,\n  );\n  const currentProjection = normalizePrincipalProjectionMembers(\n    current.projection,\n  );\n  const keyMaterialChanged = principalPolicyKeyMaterialChanged({\n    currentState: current.state,\n    previousState: previous.state,\n  });\n\n  if (\n    current.state.keyEpoch === previous.state.keyEpoch &&\n    keyMaterialChanged\n  ) {\n    return principalPolicyTransitionMismatch(\n      \"key_change_without_epoch\",\n      \"Principal policy key change requires a new key epoch\",\n    );\n  }\n\n  if (current.state.keyEpoch > previous.state.keyEpoch && !keyMaterialChanged) {\n    return principalPolicyTransitionMismatch(\n      \"epoch_advance_without_key_material\",\n      \"Principal policy key epoch advance requires new key material\",\n    );\n  }\n\n  if (\n    hasPrincipalPolicyProjectionShrink({\n      currentProjection,\n      previousProjection,\n    }) &&\n    (current.state.keyEpoch <= previous.state.keyEpoch || !keyMaterialChanged)\n  ) {\n    return principalPolicyTransitionMismatch(\n      \"shrink_without_key_rotation\",\n      \"Principal policy shrink requires a new key epoch and key material\",\n    );\n  }\n\n  if (\n    hasPrincipalPolicyGrantRemoval({\n      currentGrants: current.grants,\n      previousGrants: previous.grants,\n    }) &&\n    current.state.keyEpoch <= previous.state.keyEpoch\n  ) {\n    return principalPolicyTransitionMismatch(\n      \"grant_removal_without_key_rotation\",\n      \"Principal policy grant removal requires a new key epoch\",\n    );\n  }\n\n  return null;\n}\n\nexport function getPrincipalPolicyTransitionMismatchReason(\n  input: Parameters<typeof getPrincipalPolicyTransitionMismatch>[0],\n): string | null {\n  return getPrincipalPolicyTransitionMismatch(input)?.message ?? null;\n}\n\nexport function throwPrincipalPolicyTransitionError(\n  mismatch: PrincipalPolicyTransitionMismatch,\n): never {\n  switch (mismatch.code) {\n    case \"epoch_advance_without_key_material\":\n    case \"grant_removal_without_key_rotation\":\n    case \"key_change_without_epoch\":\n    case \"key_epoch_decrease\":\n    case \"shrink_without_key_rotation\":\n      return throwVerification(\"key_epoch_reuse\", mismatch.message);\n    case \"previous_hash_mismatch\":\n      return throwVerification(\"stale_predecessor\", mismatch.message);\n    case \"principal_mismatch\":\n    case \"version_not_contiguous\":\n      return throwVerification(\"invalid_shape\", mismatch.message);\n  }\n}\n"]}

package/internal/crypto/keying/principalPolicyTypes.d.ts

@@ -0,0 +1,126 @@
+import type { PrincipalContainerGrant, PrincipalProjectionMember, PrincipalStateMemberEnvelope, PrincipalStatePayloadCipherSuite, SignedPrincipalState } from "../principalState.js";
+import type { PrincipalPolicyExternalAuthority } from "./principalPolicyExternalAuthorityTypes.js";
+export type ManagedPrincipalKind = "group" | "organization";
+export interface ReferencedPrincipalHead {
+    principalType: ManagedPrincipalKind;
+    principalId: string;
+    version: number;
+    keyEpoch: number;
+    stateHash: string;
+    keyFingerprint: string;
+}
+export interface PrincipalPolicyCheckpoint {
+    readonly principalType: ManagedPrincipalKind;
+    readonly principalId: string;
+    readonly version: number;
+    readonly stateHash: string;
+}
+export interface PrincipalPolicySignedState extends SignedPrincipalState {
+    readonly stateHash: string;
+}
+export interface PrincipalPolicyStateChainEntry {
+    readonly state: PrincipalPolicySignedState;
+    readonly projection: readonly PrincipalProjectionMember[];
+    readonly grants: readonly PrincipalContainerGrant[];
+}
+export interface PrincipalPolicyPayload {
+    readonly principalType: ManagedPrincipalKind;
+    readonly principalId: string;
+    readonly stateHash: string;
+    readonly cipherSuite: PrincipalStatePayloadCipherSuite;
+    readonly ciphertext: string;
+    readonly ciphertextHash: string;
+}
+export interface PrincipalPolicyMemberEnvelopes {
+    readonly principalType: ManagedPrincipalKind;
+    readonly principalId: string;
+    readonly stateHash: string;
+    readonly epoch: number;
+    readonly envelopes: readonly PrincipalStateMemberEnvelope[];
+}
+export interface PrincipalPolicyBundle {
+    readonly currentState: PrincipalPolicySignedState;
+    readonly currentPayload: PrincipalPolicyPayload;
+    readonly currentProjection: readonly PrincipalProjectionMember[];
+    readonly currentGrants: readonly PrincipalContainerGrant[];
+    readonly currentMemberEnvelopes: PrincipalPolicyMemberEnvelopes;
+    readonly previousStates: readonly PrincipalPolicyStateChainEntry[];
+}
+export interface PrincipalPolicySnapshot {
+    readonly currentState: PrincipalPolicySignedState;
+    readonly currentProjection: readonly PrincipalProjectionMember[];
+    readonly currentGrants: readonly PrincipalContainerGrant[];
+    readonly previousStates: readonly PrincipalPolicyStateChainEntry[];
+}
+export interface PrincipalPolicySignerPublicKey {
+    readonly userId: string;
+    readonly signingKeyFingerprint: string;
+    readonly signingPublicKey: Uint8Array;
+}
+export interface VerifyPrincipalPolicyBundleInput {
+    readonly bundle: PrincipalPolicyBundle;
+    readonly externalAuthority?: PrincipalPolicyExternalAuthority;
+    readonly expectedReference?: ReferencedPrincipalHead;
+    readonly localCheckpoint?: PrincipalPolicyCheckpoint | null;
+    readonly signerPublicKeys: readonly PrincipalPolicySignerPublicKey[];
+}
+export interface VerifyPrincipalPolicySnapshotInput {
+    readonly snapshot: PrincipalPolicySnapshot;
+    readonly externalAuthority?: PrincipalPolicyExternalAuthority;
+    readonly expectedReference?: ReferencedPrincipalHead;
+    readonly signerPublicKeys: readonly PrincipalPolicySignerPublicKey[];
+}
+export interface NormalizedPrincipalPolicyStateChainEntry {
+    readonly state: PrincipalPolicySignedState;
+    readonly projection: PrincipalProjectionMember[];
+    readonly grants: PrincipalContainerGrant[];
+}
+declare const verifiedPrincipalPolicyBrand: unique symbol;
+declare const verifiedPrincipalPolicySnapshotBrand: unique symbol;
+export interface VerifiedPrincipalPolicy {
+    readonly principalType: ManagedPrincipalKind;
+    readonly principalId: string;
+    readonly version: number;
+    readonly keyEpoch: number;
+    readonly stateHash: string;
+    readonly state: PrincipalPolicySignedState;
+    readonly projection: PrincipalProjectionMember[];
+    readonly grants: PrincipalContainerGrant[];
+    readonly history?: readonly NormalizedPrincipalPolicyStateChainEntry[];
+    readonly checkpoint: PrincipalPolicyCheckpoint;
+    readonly [verifiedPrincipalPolicyBrand]: true;
+}
+export interface VerifiedPrincipalPolicySnapshot {
+    readonly principalType: ManagedPrincipalKind;
+    readonly principalId: string;
+    readonly version: number;
+    readonly keyEpoch: number;
+    readonly stateHash: string;
+    readonly state: PrincipalPolicySignedState;
+    readonly projection: PrincipalProjectionMember[];
+    readonly grants: PrincipalContainerGrant[];
+    readonly history: readonly NormalizedPrincipalPolicyStateChainEntry[];
+    readonly checkpoint: PrincipalPolicyCheckpoint;
+    readonly [verifiedPrincipalPolicySnapshotBrand]: true;
+}
+export type AnyVerifiedPrincipalPolicy = VerifiedPrincipalPolicy | VerifiedPrincipalPolicySnapshot;
+/** Current artifacts whose authorization history is delivered separately. */
+export type PrincipalPolicyCurrent = Omit<PrincipalPolicyBundle, "previousStates">;
+declare const verifiedCurrentBrand: unique symbol;
+/** Verified current artifacts and selected history, never a full-chain policy. */
+export interface VerifiedPrincipalPolicyCurrent extends Pick<VerifiedPrincipalPolicy, "principalType" | "principalId" | "version" | "keyEpoch" | "stateHash" | "state" | "projection" | "grants" | "checkpoint"> {
+    readonly [verifiedCurrentBrand]: true;
+    readonly retainedHistory: NonNullable<VerifiedPrincipalPolicy["history"]>;
+}
+declare const verifiedSelectionBrand: unique symbol;
+/** Public authorization only; neither full history nor current key material. */
+export interface VerifiedPrincipalPolicySelection extends Pick<VerifiedPrincipalPolicyCurrent, "principalType" | "principalId" | "version" | "keyEpoch" | "stateHash" | "state" | "projection" | "grants" | "checkpoint" | "retainedHistory"> {
+    readonly [verifiedSelectionBrand]: true;
+}
+/** Exact membership and explicitly retained citations for authorization. */
+export type PrincipalPolicyAuthorization = AnyVerifiedPrincipalPolicy | VerifiedPrincipalPolicyCurrent | VerifiedPrincipalPolicySelection;
+export declare function makeVerifiedPrincipalPolicy(value: Omit<VerifiedPrincipalPolicy, typeof verifiedPrincipalPolicyBrand>): VerifiedPrincipalPolicy;
+export declare function makeVerifiedPrincipalPolicySnapshot(value: Omit<VerifiedPrincipalPolicySnapshot, typeof verifiedPrincipalPolicySnapshotBrand>): VerifiedPrincipalPolicySnapshot;
+export declare function makeVerifiedPrincipalPolicyCurrent(value: Omit<VerifiedPrincipalPolicyCurrent, typeof verifiedCurrentBrand>): VerifiedPrincipalPolicyCurrent;
+export declare function makeVerifiedPrincipalPolicySelection(value: Omit<VerifiedPrincipalPolicySelection, typeof verifiedSelectionBrand>): VerifiedPrincipalPolicySelection;
+export {};