@kubun/credential 0.17.4 → 0.18.0

package/lib/authority.d.ts

@@ -11,6 +11,8 @@ export type CredentialAuthorityParams = {
     store: CredentialStoreAPI;
 };
 export type CredentialAuthority = {
+    /** Administer proof to bind into records signed for a non-controller owner. */
+    delegationTokens?: Array<string>;
     /**
      * The DID a key minted by this viewer belongs to.
      *
@@ -19,6 +21,8 @@ export type CredentialAuthority = {
      */
     ownerForNewKey(): Promise<string>;
     authorize(authorization: CredentialAuthorization, params: CredentialAuthorityParams): Promise<boolean>;
+    /** Revocation is reserved for the owner or a current controller-head device. */
+    authorizeRevocation?(params: CredentialAuthorityParams): Promise<boolean>;
 };
 /**
  * The stand-in until ownership is a controller/agent capability chain: the viewer

package/lib/authority.js

@@ -10,6 +10,9 @@ import { normalizeDID } from '@kokuin/token';
         async ownerForNewKey () {
             return viewerDID;
         },
+        async authorizeRevocation ({ key }) {
+            return normalizeDID(key.owner_did) === viewerDID;
+        },
         async authorize (authorization, { key, store }) {
             if (normalizeDID(key.owner_did) === viewerDID) {
                 return true;

package/lib/branch.d.ts

@@ -0,0 +1,4 @@
+/** Order branches by their introducing record op hash, then by HLC. */
+export declare function compareBranchIDs(a: string, b: string): number;
+/** Choose the same branch regardless of input order. */
+export declare function selectWinningBranch(branchIDs: ReadonlyArray<string>): string;

package/lib/branch.js

@@ -0,0 +1,24 @@
+/** Split an authenticated branch label at the last colon because HLCs contain colons. */ function splitBranchID(branchID) {
+    const boundary = branchID.lastIndexOf(':');
+    return boundary < 0 ? {
+        hlc: branchID,
+        opHash: ''
+    } : {
+        hlc: branchID.slice(0, boundary),
+        opHash: branchID.slice(boundary + 1)
+    };
+}
+/** Order branches by their introducing record op hash, then by HLC. */ export function compareBranchIDs(a, b) {
+    const left = splitBranchID(a);
+    const right = splitBranchID(b);
+    if (left.opHash !== right.opHash) {
+        return left.opHash < right.opHash ? -1 : 1;
+    }
+    return left.hlc < right.hlc ? -1 : left.hlc > right.hlc ? 1 : 0;
+}
+/** Choose the same branch regardless of input order. */ export function selectWinningBranch(branchIDs) {
+    if (branchIDs.length === 0) {
+        throw new RangeError('selectWinningBranch requires at least one branchID');
+    }
+    return branchIDs.reduce((winner, candidate)=>compareBranchIDs(candidate, winner) > 0 ? candidate : winner);
+}

package/lib/builder.d.ts

@@ -39,6 +39,11 @@ export type BuiltWrapping = {
 };
 export type BuiltKey = CredentialKeyMaterial & {
     wrappings: Array<BuiltWrapping>;
+    /**
+     * The random half of `keyID`, base64url. The id is the digest of the owner and
+     * this value, so a key record carrying it proves its id names this owner's key.
+     */
+    keyUnique: string;
 };
 export type BuildKeyParams = {
     runtime: Runtime;

package/lib/builder.js

@@ -1,5 +1,6 @@
 import { normalizeDID } from '@kokuin/token';
 import { CredentialEntryID, CredentialKeyID } from '@kubun/id';
+import { toB64U } from '@sozai/codec';
 import { InvalidCredentialFactors } from './errors.js';
 import { getSuite, SUITE_KUBUN_CRED_1 } from './suite.js';
 /**
@@ -18,7 +19,8 @@ import { getSuite, SUITE_KUBUN_CRED_1 } from './suite.js';
     const suite = getSuite(suiteID);
     const ownerDID = normalizeDID(params.ownerDID);
     const version = 1;
-    const keyID = CredentialKeyID.create(ownerDID, runtime.getRandomValues(new Uint8Array(16))).toString();
+    const unique = runtime.getRandomValues(new Uint8Array(16));
+    const keyID = CredentialKeyID.create(ownerDID, unique).toString();
     const contentKey = suite.generateContentKey(runtime);
     const wrappings = [];
     for (const factors of params.wrappings){
@@ -39,10 +41,9 @@ import { getSuite, SUITE_KUBUN_CRED_1 } from './suite.js';
             factors: descriptors,
             iv,
             wrappedKey,
-            // Populated only for the single-`did` case. A `[did, pin]` wrapping is not
-            // openable by its recipient alone, so recording one would let a lookup
-            // conclude the key opens on that device when it does not.
-            recipientDID: factors.length === 1 && factors[0]?.kind === 'did' ? factors[0].recipientDID : null
+            // Address delivery to the sole DID factor even when a PIN or passphrase
+            // is also required to open it. More than one DID names no sole recipient.
+            recipientDID: factors.filter((factor)=>factor.kind === 'did').length === 1 ? factors.find((factor)=>factor.kind === 'did')?.recipientDID ?? null : null
         });
     }
     return {
@@ -51,7 +52,8 @@ import { getSuite, SUITE_KUBUN_CRED_1 } from './suite.js';
         suite: suiteID,
         version,
         contentKey,
-        wrappings
+        wrappings,
+        keyUnique: toB64U(unique)
     };
 }
 /** Encrypt one value under a key already built or already open. */ export function buildCredentialEntry(params) {

package/lib/canonical-token.d.ts

@@ -0,0 +1,2 @@
+/** Check that a compact token has exactly the spelling produced by its signer. */
+export declare function isCanonicalCompactToken(token: string): boolean;

package/lib/canonical-token.js

@@ -0,0 +1,10 @@
+import { fromB64U, toB64U } from '@sozai/codec';
+/** Check that a compact token has exactly the spelling produced by its signer. */ export function isCanonicalCompactToken(token) {
+    const segments = token.split('.');
+    if (segments.length !== 3) return false;
+    try {
+        return segments.every((segment)=>toB64U(fromB64U(segment)) === segment);
+    } catch  {
+        return false;
+    }
+}

package/lib/errors.d.ts

@@ -6,7 +6,7 @@ import type { CredentialAuthorization } from './authority.js';
  * without deciding what a caller is meant to match on. Messages are for people
  * and change; these do not.
  */
-export type CredentialErrorCode = 'CREDENTIAL_ALIAS_ALREADY_BOUND' | 'CREDENTIAL_BIND_NOT_AUTHORIZED' | 'CREDENTIAL_ENTRY_ALREADY_ALIASED' | 'CREDENTIAL_ERROR' | 'CREDENTIAL_FACTOR_UNAVAILABLE' | 'CREDENTIAL_FACTORS_INVALID' | 'CREDENTIAL_INVALID_ENTRY' | 'CREDENTIAL_KEY_LOCKED' | 'CREDENTIAL_KEY_VERSION_MISMATCH' | 'CREDENTIAL_NOT_AUTHORIZED' | 'CREDENTIAL_NOT_FOUND' | 'CREDENTIAL_PIN_REJECTED' | 'CREDENTIAL_SECRET_REJECTED' | 'CREDENTIAL_SUPERSEDED_BRANCH' | 'CREDENTIAL_SUITE_UNSUPPORTED' | 'CREDENTIAL_TAMPERED' | 'CREDENTIAL_UNOPENABLE' | 'CREDENTIAL_WRAPPING_AMBIGUOUS';
+export type CredentialErrorCode = 'CREDENTIAL_ALIAS_ALREADY_BOUND' | 'CREDENTIAL_BIND_NOT_AUTHORIZED' | 'CREDENTIAL_ENTRY_ALREADY_ALIASED' | 'CREDENTIAL_ENTRY_CONFLICT' | 'CREDENTIAL_ENTRY_OWNER_MISMATCH' | 'CREDENTIAL_ERROR' | 'CREDENTIAL_FACTOR_UNAVAILABLE' | 'CREDENTIAL_FACTORS_INVALID' | 'CREDENTIAL_GRANT_COPY_UNAVAILABLE' | 'CREDENTIAL_GRANT_OWNER_AMBIGUOUS' | 'CREDENTIAL_GRANT_REHOME_NOT_AUTHORIZED' | 'CREDENTIAL_GRANT_ACCOUNT_MISMATCH' | 'CREDENTIAL_INVALID_ENTRY' | 'CREDENTIAL_KEY_LOCKED' | 'CREDENTIAL_KEY_VERSION_MISMATCH' | 'CREDENTIAL_MANAGER_STORE_MISMATCH' | 'CREDENTIAL_NOT_AUTHORIZED' | 'CREDENTIAL_NOT_FOUND' | 'CREDENTIAL_REPAIR_PENDING' | 'CREDENTIAL_RECIPIENT_REVOKED' | 'CREDENTIAL_PIN_REJECTED' | 'CREDENTIAL_SECRET_REJECTED' | 'CREDENTIAL_SUPERSEDED_BRANCH' | 'CREDENTIAL_SUITE_UNSUPPORTED' | 'CREDENTIAL_TAMPERED' | 'CREDENTIAL_UNOPENABLE' | 'CREDENTIAL_WRAPPING_AMBIGUOUS';
 export type CredentialErrorOptions = ErrorOptions & {
     code: CredentialErrorCode;
 };
@@ -28,6 +28,10 @@ export declare class CredentialError extends Error {
     constructor(message: string, options: CredentialErrorOptions);
     get code(): CredentialErrorCode;
 }
+/** A credential manager was built over a different store than the write transaction. */
+export declare class CredentialManagerStoreMismatch extends CredentialError {
+    constructor();
+}
 /** A wrapping needs a factor kind this device cannot supply. */
 export declare class NoAvailableFactor extends CredentialError {
     #private;
@@ -72,6 +76,12 @@ export declare class CredentialSupersededBranch extends CredentialError {
     get entryBranchID(): string;
     get winnerBranchID(): string;
 }
+/** A fork has retained data, but this device must retry after a peer repairs it. */
+export declare class CredentialRepairPending extends CredentialError {
+    #private;
+    constructor(keyID: string);
+    get keyID(): string;
+}
 /**
  * A wrapping carrying a user-supplied factor did not authenticate.
  *
@@ -120,6 +130,10 @@ export declare class CredentialNotAuthorized extends CredentialError {
     constructor(authorization: CredentialAuthorization, keyID: string);
     get authorization(): CredentialAuthorization;
 }
+/** A key-specific revocation prevents this recipient from receiving another wrapping. */
+export declare class CredentialRecipientRevoked extends CredentialError {
+    constructor(keyID: string, recipientDID: string);
+}
 /** No key, wrapping or entry under that id. */
 export declare class CredentialNotFound extends CredentialError {
     constructor(what: string, id: string);
@@ -155,6 +169,30 @@ export declare class CredentialKeyLocked extends CredentialError {
 export declare class CredentialKeyVersionMismatch extends CredentialError {
     constructor(entryID: string, entryVersion: number, keyVersion: number);
 }
+/** An entry cannot move to a key belonging to another owner. */
+export declare class CredentialEntryOwnerMismatch extends CredentialError {
+    constructor(entryID: string, sourceOwnerDID: string, targetOwnerDID: string);
+}
+/** A conditional entry write could not settle after repeated key changes. */
+export declare class CredentialEntryConflict extends CredentialError {
+    constructor(entryID: string);
+}
+/** The destination has no addressable local live copy of the grant it was asked to adopt. */
+export declare class CredentialGrantCopyUnavailable extends CredentialError {
+    constructor(providerName: string, ownerDID: string, fromDeviceDID: string);
+}
+/** A grant ID has live rows under more than one owner and no source was selected. */
+export declare class CredentialGrantOwnerAmbiguous extends CredentialError {
+    constructor(entryID: string, owners: ReadonlyArray<string>);
+}
+/** Replacing a grant requires authority over every old and requested key owner. */
+export declare class CredentialGrantRehomeNotAuthorized extends CredentialError {
+    constructor(entryID: string);
+}
+/** A selected grant belongs to another account or uses an unrelated key owner. */
+export declare class CredentialGrantAccountMismatch extends CredentialError {
+    constructor(providerName: string, ownerDID: string);
+}
 /**
  * Every wrapping for the key was tried and none opened.
  *

package/lib/errors.js

@@ -21,6 +21,14 @@
         return this.#code;
     }
 }
+/** A credential manager was built over a different store than the write transaction. */ export class CredentialManagerStoreMismatch extends CredentialError {
+    constructor(){
+        super('Credential manager is not bound to the transaction credential store', {
+            code: 'CREDENTIAL_MANAGER_STORE_MISMATCH'
+        });
+        this.name = 'CredentialManagerStoreMismatch';
+    }
+}
 /** A wrapping needs a factor kind this device cannot supply. */ export class NoAvailableFactor extends CredentialError {
     #kind;
     constructor(kind){
@@ -103,6 +111,19 @@
         return this.#winnerBranchID;
     }
 }
+/** A fork has retained data, but this device must retry after a peer repairs it. */ export class CredentialRepairPending extends CredentialError {
+    #keyID;
+    constructor(keyID){
+        super(`Credential fork repair pending for key ${keyID}`, {
+            code: 'CREDENTIAL_REPAIR_PENDING'
+        });
+        this.name = 'CredentialRepairPending';
+        this.#keyID = keyID;
+    }
+    get keyID() {
+        return this.#keyID;
+    }
+}
 /**
  * A wrapping carrying a user-supplied factor did not authenticate.
  *
@@ -173,6 +194,14 @@
         return this.#authorization;
     }
 }
+/** A key-specific revocation prevents this recipient from receiving another wrapping. */ export class CredentialRecipientRevoked extends CredentialError {
+    constructor(keyID, recipientDID){
+        super(`Recipient ${recipientDID} is revoked for credential key ${keyID}`, {
+            code: 'CREDENTIAL_RECIPIENT_REVOKED'
+        });
+        this.name = 'CredentialRecipientRevoked';
+    }
+}
 /** No key, wrapping or entry under that id. */ export class CredentialNotFound extends CredentialError {
     constructor(what, id){
         super(`${what} not found: ${id}`, {
@@ -227,6 +256,54 @@
         this.name = 'CredentialKeyVersionMismatch';
     }
 }
+/** An entry cannot move to a key belonging to another owner. */ export class CredentialEntryOwnerMismatch extends CredentialError {
+    constructor(entryID, sourceOwnerDID, targetOwnerDID){
+        super(`Credential entry ${entryID} belongs to ${sourceOwnerDID} and cannot move to a key owned by ${targetOwnerDID}`, {
+            code: 'CREDENTIAL_ENTRY_OWNER_MISMATCH'
+        });
+        this.name = 'CredentialEntryOwnerMismatch';
+    }
+}
+/** A conditional entry write could not settle after repeated key changes. */ export class CredentialEntryConflict extends CredentialError {
+    constructor(entryID){
+        super(`Credential entry ${entryID} changed during the write; retry the operation`, {
+            code: 'CREDENTIAL_ENTRY_CONFLICT'
+        });
+        this.name = 'CredentialEntryConflict';
+    }
+}
+/** The destination has no addressable local live copy of the grant it was asked to adopt. */ export class CredentialGrantCopyUnavailable extends CredentialError {
+    constructor(providerName, ownerDID, fromDeviceDID){
+        super(`No addressable local copy of ${providerName} grant for ${ownerDID} from device ${fromDeviceDID} is available for adoption`, {
+            code: 'CREDENTIAL_GRANT_COPY_UNAVAILABLE'
+        });
+        this.name = 'CredentialGrantCopyUnavailable';
+    }
+}
+/** A grant ID has live rows under more than one owner and no source was selected. */ export class CredentialGrantOwnerAmbiguous extends CredentialError {
+    constructor(entryID, owners){
+        super(`Credential grant ${entryID} has multiple source owners: ${owners.join(', ')}`, {
+            code: 'CREDENTIAL_GRANT_OWNER_AMBIGUOUS'
+        });
+        this.name = 'CredentialGrantOwnerAmbiguous';
+    }
+}
+/** Replacing a grant requires authority over every old and requested key owner. */ export class CredentialGrantRehomeNotAuthorized extends CredentialError {
+    constructor(entryID){
+        super(`Cannot replace credential grant ${entryID} without authority over its key owners`, {
+            code: 'CREDENTIAL_GRANT_REHOME_NOT_AUTHORIZED'
+        });
+        this.name = 'CredentialGrantRehomeNotAuthorized';
+    }
+}
+/** A selected grant belongs to another account or uses an unrelated key owner. */ export class CredentialGrantAccountMismatch extends CredentialError {
+    constructor(providerName, ownerDID){
+        super(`The selected ${providerName} grant does not belong to ${ownerDID}`, {
+            code: 'CREDENTIAL_GRANT_ACCOUNT_MISMATCH'
+        });
+        this.name = 'CredentialGrantAccountMismatch';
+    }
+}
 /**
  * Every wrapping for the key was tried and none opened.
  *

package/lib/fork-repair.d.ts

@@ -0,0 +1,19 @@
+import type { CredentialManager } from './manager.js';
+import type { FactorInputs } from './suite.js';
+export type ForkRepairResult = {
+    status: 'rotated';
+    version: number;
+} | {
+    status: 'not-needed';
+} | {
+    status: 'pending';
+};
+export type ForkRepairAPI = {
+    repairFork(keyID: string, inputs?: FactorInputs): Promise<ForkRepairResult>;
+};
+/** The manager owns signing authority and its shared clock; use that same instance for repair. */
+export declare function repairCredentialFork(params: {
+    keyID: string;
+    manager: CredentialManager;
+    inputs?: FactorInputs;
+}): Promise<ForkRepairResult>;

package/lib/fork-repair.js

@@ -0,0 +1,3 @@
+/** The manager owns signing authority and its shared clock; use that same instance for repair. */ export async function repairCredentialFork(params) {
+    return await params.manager.repairFork(params.keyID, params.inputs);
+}

package/lib/grantor-authority.d.ts

@@ -0,0 +1,26 @@
+import { type MethodRegistry, type SigningIdentity } from '@kokuin/token';
+/**
+ * What a grantor signs when handing a credential-wrapping op to a recipient:
+ * binds the op to a monotonic refresh sequence. Domain separation from other
+ * signed payloads comes from the `kind` marker plus the structural check in
+ * `verifyGrantorAuthority` -- `signToken` itself has no domain override.
+ */
+export type GrantorAuthorityClaim = {
+    kind: 'credential/grantor-authority';
+    wrappingOpHash: string;
+    refreshSeq: number;
+    grantorDID: string;
+    ownerDID: string;
+    recipientDID: string;
+    delegationTokens: Array<string>;
+};
+/** The envelope carried on the wire and persisted is the signed token string itself. */
+export type GrantorAuthorityEnvelope = string;
+export declare function signGrantorAuthority(identity: SigningIdentity, claim: Omit<GrantorAuthorityClaim, 'kind' | 'grantorDID'>): Promise<GrantorAuthorityEnvelope>;
+/**
+ * Verify a grantor-authority envelope and extract its claim. Returns `null`
+ * (never throws) when the token is unparseable, unsigned (`alg: 'none'`), or
+ * structurally not a grantor-authority claim -- `grantorDID` is trusted only
+ * from the verified `iss`, never from a same-named field in the payload.
+ */
+export declare function verifyGrantorAuthority(envelope: GrantorAuthorityEnvelope, methods?: MethodRegistry): Promise<GrantorAuthorityClaim | null>;

package/lib/grantor-authority.js

@@ -0,0 +1,43 @@
+import { isVerifiedToken, normalizeDID, stringifyToken, verifyToken } from '@kokuin/token';
+export async function signGrantorAuthority(identity, claim) {
+    const fullClaim = {
+        kind: 'credential/grantor-authority',
+        grantorDID: identity.id,
+        ...claim
+    };
+    const signed = await identity.signToken(fullClaim, {
+        embedLongForm: true
+    });
+    return stringifyToken(signed);
+}
+/**
+ * Verify a grantor-authority envelope and extract its claim. Returns `null`
+ * (never throws) when the token is unparseable, unsigned (`alg: 'none'`), or
+ * structurally not a grantor-authority claim -- `grantorDID` is trusted only
+ * from the verified `iss`, never from a same-named field in the payload.
+ */ export async function verifyGrantorAuthority(envelope, methods) {
+    let verified;
+    try {
+        verified = await verifyToken(envelope, {
+            methods
+        });
+    } catch  {
+        return null;
+    }
+    if (!isVerifiedToken(verified)) {
+        return null;
+    }
+    const { iss, kind, wrappingOpHash, refreshSeq, ownerDID, recipientDID, delegationTokens } = verified.payload;
+    if (kind !== 'credential/grantor-authority' || typeof wrappingOpHash !== 'string' || typeof refreshSeq !== 'number' || typeof ownerDID !== 'string' || typeof recipientDID !== 'string' || !Array.isArray(delegationTokens) || !delegationTokens.every((token)=>typeof token === 'string')) {
+        return null;
+    }
+    return {
+        kind: 'credential/grantor-authority',
+        wrappingOpHash,
+        refreshSeq,
+        grantorDID: normalizeDID(iss),
+        ownerDID,
+        recipientDID,
+        delegationTokens
+    };
+}

package/lib/index.d.ts

@@ -1,26 +1,35 @@
-export type { CreateCredentialAPIParams, CredentialAPI } from './api.js';
+export type { AdoptGrantParams, AdoptGrantResult, GrantAddress } from '@kubun/credential-types';
+export type { AdoptGrantRecoveryParams, CreateCredentialAPIParams, CreateCredentialParams, CredentialAPI, } from './api.js';
 export { createCredentialAPI } from './api.js';
 export type { CredentialAuthority, CredentialAuthorityParams, CredentialAuthorization, } from './authority.js';
 export { createDeviceAuthority } from './authority.js';
+export { compareBranchIDs, selectWinningBranch } from './branch.js';
 export type { BuildEntryParams, BuildKeyParams, BuiltEntry, BuiltKey, BuiltWrapping, CredentialKeyMaterial, } from './builder.js';
 export { buildCredentialEntry, buildCredentialKey } from './builder.js';
+export { isCanonicalCompactToken } from './canonical-token.js';
 export type { CredentialEntryDigestInput, CredentialKeyDigestInput, CredentialWrappingDigestInput, } from './digest.js';
 export { credentialEntriesDigest, credentialEntryDigest, credentialKeyDigest, credentialWrappingDigest, digestParts, } from './digest.js';
 export type { CredentialErrorCode, CredentialErrorOptions } from './errors.js';
-export { AmbiguousCredentialWrapping, CredentialAliasAlreadyBound, CredentialBindNotAuthorized, CredentialEntryAlreadyAliased, CredentialError, CredentialInvalidEntry, CredentialKeyLocked, CredentialKeyVersionMismatch, CredentialNotAuthorized, CredentialNotFound, CredentialPinRejected, CredentialSecretRejected, CredentialSupersededBranch, CredentialTampered, CredentialUnopenable, InvalidCredentialFactors, NoAvailableFactor, UnsupportedCredentialSuite, } from './errors.js';
-export type { CreateCredentialManagerParams, CreateKeyParams, CredentialGrantResult, CredentialKeyStatus, CredentialManager, CredentialUnopenableReason, FactorChangeParams, GrantKeyParams, ReKeyEntryParams, RotateKeyParams, } from './manager.js';
+export { AmbiguousCredentialWrapping, CredentialAliasAlreadyBound, CredentialBindNotAuthorized, CredentialEntryAlreadyAliased, CredentialEntryConflict, CredentialEntryOwnerMismatch, CredentialError, CredentialGrantAccountMismatch, CredentialGrantCopyUnavailable, CredentialGrantOwnerAmbiguous, CredentialGrantRehomeNotAuthorized, CredentialInvalidEntry, CredentialKeyLocked, CredentialKeyVersionMismatch, CredentialManagerStoreMismatch, CredentialNotAuthorized, CredentialNotFound, CredentialPinRejected, CredentialRecipientRevoked, CredentialRepairPending, CredentialSecretRejected, CredentialSupersededBranch, CredentialTampered, CredentialUnopenable, InvalidCredentialFactors, NoAvailableFactor, UnsupportedCredentialSuite, } from './errors.js';
+export type { ForkRepairAPI, ForkRepairResult } from './fork-repair.js';
+export { repairCredentialFork } from './fork-repair.js';
+export type { GrantorAuthorityClaim, GrantorAuthorityEnvelope } from './grantor-authority.js';
+export { signGrantorAuthority, verifyGrantorAuthority } from './grantor-authority.js';
+export type { CreateCredentialManagerParams, CreateKeyParams, CredentialEntryAddress, CredentialGrantResult, CredentialKeyStatus, CredentialManager, CredentialUnopenableReason, FactorChangeParams, GrantEntryParams, GrantKeyParams, RecoverRemovedDevicesParams, ReKeyCredentialEntryParams, ReKeyEntryParams, RotateKeyParams, UpdateCredentialEntryIfUnchangedParams, } from './manager.js';
 export { createCredentialManager } from './manager.js';
-export type { CredentialOpClaim, CredentialOpSigner, CredentialOpSubject, CredentialPutSubject, CredentialRowSubject, VerifiedCredentialOp, } from './op.js';
-export { compareBranchIDs, createCredentialOpSigner, credentialOpMatchesPut, credentialOpMatchesRow, credentialPutDigest, credentialRowDigest, selectWinningBranch, verifyCredentialOp, } from './op.js';
+export type { CredentialManifestClaim, CredentialManifestEnvelope } from './manifest-token.js';
+export { signCredentialManifest, verifyCredentialManifest } from './manifest-token.js';
 export type { PinThrottle, PinThrottleParams } from './pin-throttle.js';
 export { createPinThrottle, DEFAULT_BASE_DELAY, DEFAULT_FREE_ATTEMPTS, DEFAULT_MAX_DELAY, } from './pin-throttle.js';
 export type { CredentialEntryProvenance } from './provenance.js';
 export { entryProvenanceFields } from './provenance.js';
 export type { DBCredentialProviderParams } from './provider.js';
 export { DBCredentialProvider, deserializeCredential, serializeCredential } from './provider.js';
+export type { CredentialRecordType, CredentialRecordTypeDeps } from './record-types.js';
+export { CredentialRecordHookError, credentialGrantEntryID, credentialHolderTypes, credentialKeyVersionReader, credentialProofAuthorizer, credentialRecordTypes, credentialStoreForHooks, } from './record-types.js';
 export type { RefreshEvents, RefreshedEvent, RefreshFailedEvent, RefreshFailureCategory, RefreshingCredentialProviderParams, RefreshOutcome, } from './refreshing-credential-provider.js';
 export { RefreshingCredentialProvider } from './refreshing-credential-provider.js';
-export type { Argon2Cost, CredentialSuite, FactorInput, FactorInputs, SecretFactorKind, } from './suite.js';
+export type { Argon2Cost, CredentialSuite, EncryptEntryResult, FactorInput, FactorInputs, SecretFactorKind, } from './suite.js';
 export { DEFAULT_ARGON2_COST, getSuite, isSupportedSuite, SUITE_KUBUN_CRED_1 } from './suite.js';
 export { assertValidCredentialShape } from './validate.js';
 export { CREDENTIAL_ADMINISTER_ACTION, credentialUserResource } from './vocabulary.js';

package/lib/index.js

@@ -1,13 +1,18 @@
 export { createCredentialAPI } from './api.js';
 export { createDeviceAuthority } from './authority.js';
+export { compareBranchIDs, selectWinningBranch } from './branch.js';
 export { buildCredentialEntry, buildCredentialKey } from './builder.js';
+export { isCanonicalCompactToken } from './canonical-token.js';
 export { credentialEntriesDigest, credentialEntryDigest, credentialKeyDigest, credentialWrappingDigest, digestParts } from './digest.js';
-export { AmbiguousCredentialWrapping, CredentialAliasAlreadyBound, CredentialBindNotAuthorized, CredentialEntryAlreadyAliased, CredentialError, CredentialInvalidEntry, CredentialKeyLocked, CredentialKeyVersionMismatch, CredentialNotAuthorized, CredentialNotFound, CredentialPinRejected, CredentialSecretRejected, CredentialSupersededBranch, CredentialTampered, CredentialUnopenable, InvalidCredentialFactors, NoAvailableFactor, UnsupportedCredentialSuite } from './errors.js';
+export { AmbiguousCredentialWrapping, CredentialAliasAlreadyBound, CredentialBindNotAuthorized, CredentialEntryAlreadyAliased, CredentialEntryConflict, CredentialEntryOwnerMismatch, CredentialError, CredentialGrantAccountMismatch, CredentialGrantCopyUnavailable, CredentialGrantOwnerAmbiguous, CredentialGrantRehomeNotAuthorized, CredentialInvalidEntry, CredentialKeyLocked, CredentialKeyVersionMismatch, CredentialManagerStoreMismatch, CredentialNotAuthorized, CredentialNotFound, CredentialPinRejected, CredentialRecipientRevoked, CredentialRepairPending, CredentialSecretRejected, CredentialSupersededBranch, CredentialTampered, CredentialUnopenable, InvalidCredentialFactors, NoAvailableFactor, UnsupportedCredentialSuite } from './errors.js';
+export { repairCredentialFork } from './fork-repair.js';
+export { signGrantorAuthority, verifyGrantorAuthority } from './grantor-authority.js';
 export { createCredentialManager } from './manager.js';
-export { compareBranchIDs, createCredentialOpSigner, credentialOpMatchesPut, credentialOpMatchesRow, credentialPutDigest, credentialRowDigest, selectWinningBranch, verifyCredentialOp } from './op.js';
+export { signCredentialManifest, verifyCredentialManifest } from './manifest-token.js';
 export { createPinThrottle, DEFAULT_BASE_DELAY, DEFAULT_FREE_ATTEMPTS, DEFAULT_MAX_DELAY } from './pin-throttle.js';
 export { entryProvenanceFields } from './provenance.js';
 export { DBCredentialProvider, deserializeCredential, serializeCredential } from './provider.js';
+export { CredentialRecordHookError, credentialGrantEntryID, credentialHolderTypes, credentialKeyVersionReader, credentialProofAuthorizer, credentialRecordTypes, credentialStoreForHooks } from './record-types.js';
 export { RefreshingCredentialProvider } from './refreshing-credential-provider.js';
 export { DEFAULT_ARGON2_COST, getSuite, isSupportedSuite, SUITE_KUBUN_CRED_1 } from './suite.js';
 export { assertValidCredentialShape } from './validate.js';

package/lib/key-cache.d.ts

@@ -19,8 +19,8 @@ export type KeyCacheParams = {
  */
 export type KeyCache = {
     /**
-     * The cached key and the branch it resolved to, or null if absent, expired,
-     * or from a superseded version. A cache hit still surfaces the branch so a
+     * The cached key and the branch it resolved to, or null if absent or expired.
+     * A cache hit still surfaces the branch so a
      * post-fork write joins the same branch the first open resolved.
      */
     get(keyID: string, keyVersion: number): {
@@ -28,12 +28,13 @@ export type KeyCache = {
         branchID: string;
     } | null;
     /**
-     * Whether an unexpired, current-version key is cached, without materialising a
+     * Whether an unexpired key at this version is cached, without materialising a
      * copy of it. Presence-only callers (`status`) use this so a probe never mints
      * a secret buffer it immediately discards.
      */
     has(keyID: string, keyVersion: number): boolean;
     set(keyID: string, contentKey: Uint8Array, keyVersion: number, branchID: string): void;
+    evictVersion(keyID: string, keyVersion: number): void;
     evict(keyID: string): void;
     evictAll(): void;
 };

package/lib/key-cache.js

@@ -11,25 +11,30 @@ export function createKeyCache(params = {}) {
    * JavaScript cannot promise no interpreter-level copy survives, so this is
    * best-effort hygiene, not a guarantee that no copy of the key remains.
    */ function evict(keyID) {
-        const cached = entries.get(keyID);
-        if (cached != null) {
-            cached.contentKey.fill(0);
-            entries.delete(keyID);
-        }
+        const versions = entries.get(keyID);
+        if (versions == null) return;
+        for (const cached of versions.values())cached.contentKey.fill(0);
+        entries.delete(keyID);
+    }
+    function evictVersion(keyID, keyVersion) {
+        const versions = entries.get(keyID);
+        const cached = versions?.get(keyVersion);
+        if (cached == null) return;
+        cached.contentKey.fill(0);
+        versions?.delete(keyVersion);
+        if (versions?.size === 0) entries.delete(keyID);
     }
     /**
-   * The still-valid cached entry for this key/version, or null — evicting a
-   * stale one on the way. A rotation invalidates the cache as surely as time
-   * does: serving the pre-rotation key would decrypt entries the rotation was
-   * retiring. Shared by `get` and `has` so both apply identical validity and
+   * The still-valid cached entry for this key/version, or null — evicting an
+   * expired one on the way. Shared by `get` and `has` so both apply identical validity and
    * lazy-eviction rules; neither exposes the buffer.
    */ function live(keyID, keyVersion) {
-        const cached = entries.get(keyID);
+        const cached = entries.get(keyID)?.get(keyVersion);
         if (cached == null) {
             return null;
         }
-        if (now() - cached.unlockedAt >= ttl || cached.keyVersion !== keyVersion) {
-            evict(keyID);
+        if (now() - cached.unlockedAt >= ttl) {
+            evictVersion(keyID, keyVersion);
             return null;
         }
         return cached;
@@ -53,18 +58,20 @@ export function createKeyCache(params = {}) {
             return live(keyID, keyVersion) != null;
         },
         set (keyID, contentKey, keyVersion, branchID) {
-            evict(keyID);
+            evictVersion(keyID, keyVersion);
             // Store a private clone so the caller's buffer is never the cached buffer:
             // the caller may zero its own copy after use without disturbing the cache,
             // and the cache may zero its clone on evict without disturbing the caller.
-            entries.set(keyID, {
+            const versions = entries.get(keyID) ?? new Map();
+            versions.set(keyVersion, {
                 contentKey: contentKey.slice(),
-                keyVersion,
                 branchID,
                 unlockedAt: now()
             });
+            entries.set(keyID, versions);
         },
         evict,
+        evictVersion,
         evictAll () {
             for (const keyID of [
                 ...entries.keys()

package/lib/manager-context.d.ts

@@ -0,0 +1,50 @@
+import { type KeyAgreementIdentity, type SigningIdentity } from '@kokuin/token';
+import { HLC } from '@kubun/hlc';
+import type { CredentialFactorDescriptor, CredentialStoreAPI } from '@kubun/store-credential';
+import type { Runtime } from '@sozai/runtime';
+import { type CredentialAuthority } from './authority.js';
+import { type KeyCache } from './key-cache.js';
+import type { OpenFunctions } from './manager-open.js';
+import type { RecordFunctions } from './manager-records.js';
+import type { RemovalRecoveryFunctions } from './manager-removal-recovery.js';
+import type { RotateFunctions } from './manager-rotate.js';
+import type { CreateCredentialManagerParams, CredentialManager } from './manager-types.js';
+import { type PinThrottle } from './pin-throttle.js';
+import type { SecretFactorKind } from './suite.js';
+/** Kinds a user can be prompted for, as opposed to ones held as key material. */
+export declare const SECRET_FACTOR_KINDS: ReadonlyArray<SecretFactorKind>;
+export declare function wrappingNamesRemovedDevice(wrapping: {
+    recipient_did: string | null;
+    factors: ReadonlyArray<CredentialFactorDescriptor>;
+}, removed: ReadonlySet<string>): boolean;
+export declare function isSecretFactorKind(kind: string): kind is SecretFactorKind;
+export type ManagerState = {
+    inFlight: Map<string, Promise<void>>;
+    keyGeneration: Map<string, number>;
+    lockAllEpoch: number;
+    floorPromise?: Promise<void>;
+    completedRecoveryHead?: string;
+};
+export type ManagerContext = {
+    params: CreateCredentialManagerParams;
+    store: CredentialStoreAPI;
+    identity: SigningIdentity;
+    runtime: Runtime;
+    hlc: HLC;
+    authority: CredentialAuthority;
+    decrypting: KeyAgreementIdentity | null;
+    cache: KeyCache;
+    throttle: PinThrottle;
+    state: ManagerState;
+    ensureFloored: () => Promise<void>;
+    nextHLC: () => Promise<string>;
+};
+export type ManagerInternals = {
+    readonly records: RecordFunctions;
+    readonly open: OpenFunctions;
+    readonly rotate: RotateFunctions;
+    readonly removalRecovery: RemovalRecoveryFunctions;
+    readonly manager: CredentialManager;
+    createManager: (params: CreateCredentialManagerParams) => CredentialManager;
+};
+export declare function createManagerContext(params: CreateCredentialManagerParams): ManagerContext;