@kubun/credential 0.17.3 → 0.18.0

package/lib/manifest-token.d.ts

@@ -0,0 +1,31 @@
+import { type MethodRegistry, type SigningIdentity } from '@kokuin/token';
+/**
+ * What a grantor signs to record the set of keys it granted a recipient: a
+ * claim the recipient checks its store against to prove completeness. Domain
+ * separation from other signed payloads comes from the `kind` marker plus the
+ * structural check in `verifyCredentialManifest` -- `signToken` has no
+ * domain override of its own.
+ */
+export type CredentialManifestClaim = {
+    kind: 'credential/key-manifest';
+    ownerDID: string;
+    recipientDID: string;
+    grantorDID: string;
+    epoch: number;
+    sequence: number;
+    keys: Array<{
+        keyID: string;
+        version: number;
+    }>;
+    issuedAt: string;
+};
+/** The envelope carried on the wire and persisted is the signed token string itself. */
+export type CredentialManifestEnvelope = string;
+export declare function signCredentialManifest(identity: SigningIdentity, claim: Omit<CredentialManifestClaim, 'kind' | 'grantorDID'>): Promise<CredentialManifestEnvelope>;
+/**
+ * Verify a credential-manifest envelope and extract its claim. Returns `null`
+ * (never throws) when the token is unparseable, unsigned (`alg: 'none'`), or
+ * structurally not a credential-manifest claim -- `grantorDID` is trusted
+ * only from the verified `iss`, never from a same-named field in the payload.
+ */
+export declare function verifyCredentialManifest(envelope: CredentialManifestEnvelope, methods?: MethodRegistry): Promise<CredentialManifestClaim | null>;

package/lib/manifest-token.js

@@ -0,0 +1,51 @@
+import { isVerifiedToken, normalizeDID, stringifyToken, verifyToken } from '@kokuin/token';
+/**
+ * Check that a value is a finite, safe, positive integer (>= 1).
+ * Rejects NaN, Infinity, floats, negatives, and zero.
+ */ const isPosInt = (n)=>typeof n === 'number' && Number.isSafeInteger(n) && n >= 1;
+export async function signCredentialManifest(identity, claim) {
+    const fullClaim = {
+        kind: 'credential/key-manifest',
+        grantorDID: identity.id,
+        ...claim
+    };
+    const signed = await identity.signToken(fullClaim, {
+        embedLongForm: true
+    });
+    return stringifyToken(signed);
+}
+function isValidKeysArray(value) {
+    return Array.isArray(value) && value.every((entry)=>entry != null && typeof entry === 'object' && typeof entry.keyID === 'string' && isPosInt(entry.version));
+}
+/**
+ * Verify a credential-manifest envelope and extract its claim. Returns `null`
+ * (never throws) when the token is unparseable, unsigned (`alg: 'none'`), or
+ * structurally not a credential-manifest claim -- `grantorDID` is trusted
+ * only from the verified `iss`, never from a same-named field in the payload.
+ */ export async function verifyCredentialManifest(envelope, methods) {
+    let verified;
+    try {
+        verified = await verifyToken(envelope, {
+            methods
+        });
+    } catch  {
+        return null;
+    }
+    if (!isVerifiedToken(verified)) {
+        return null;
+    }
+    const { iss, kind, ownerDID, recipientDID, epoch, sequence, keys, issuedAt } = verified.payload;
+    if (kind !== 'credential/key-manifest' || typeof ownerDID !== 'string' || typeof recipientDID !== 'string' || !isPosInt(epoch) || !isPosInt(sequence) || typeof issuedAt !== 'string' || !isValidKeysArray(keys)) {
+        return null;
+    }
+    return {
+        kind: 'credential/key-manifest',
+        ownerDID,
+        recipientDID,
+        grantorDID: normalizeDID(iss),
+        epoch,
+        sequence,
+        keys,
+        issuedAt
+    };
+}

package/lib/provider.d.ts

@@ -1,11 +1,11 @@
-import type { AliasBindingCredentialProvider, Credential, CredentialProvider, EntryPairedCredentialProvider } from '@kubun/credential-types';
+import type { AliasBindingCredentialProvider, Credential, CredentialProvider, EntryPairedCredentialProvider, GrantAddress, VersionedEntryCredentialProvider } from '@kubun/credential-types';
 import type { CredentialAPI } from './api.js';
 export declare function serializeCredential(credential: Credential): string;
 export declare function deserializeCredential(raw: string | Record<string, unknown>): Credential;
 export type DBCredentialProviderParams = {
     api: CredentialAPI;
 };
-export declare class DBCredentialProvider implements CredentialProvider, AliasBindingCredentialProvider, EntryPairedCredentialProvider {
+export declare class DBCredentialProvider implements CredentialProvider, AliasBindingCredentialProvider, EntryPairedCredentialProvider, VersionedEntryCredentialProvider {
     #private;
     constructor(params: DBCredentialProviderParams);
     get(providerName: string, ownerDID: string): Promise<Credential | null>;
@@ -17,6 +17,7 @@ export declare class DBCredentialProvider implements CredentialProvider, AliasBi
         controllerWrappableDID?: string;
     }): Promise<void>;
     delete(providerName: string, ownerDID: string): Promise<void>;
+    update(address: GrantAddress, change: (current: Credential | null) => Credential): Promise<void>;
     bindAlias(providerName: string, ownerDID: string, entryID: string): Promise<void>;
     getCredentialRef(providerName: string, ownerDID: string): Promise<{
         credential: Credential;
@@ -28,4 +29,16 @@ export declare class DBCredentialProvider implements CredentialProvider, AliasBi
         entryID: string;
         credential: Credential;
     }): Promise<'updated' | 'absent'>;
+    getVersionedCredentialRef(providerName: string, ownerDID: string): Promise<{
+        credential: Credential;
+        entryID: string;
+        version: string;
+    } | null>;
+    setCredentialForEntryIfUnchanged(params: {
+        providerName: string;
+        ownerDID: string;
+        entryID: string;
+        credential: Credential;
+        expectedVersion: string;
+    }): Promise<'updated' | 'absent' | 'superseded'>;
 }

package/lib/provider.js

@@ -1,3 +1,6 @@
+import { normalizeDID } from '@kokuin/token';
+import { CredentialUpdateUnavailableError } from '@kubun/credential-types';
+import { CredentialBindNotAuthorized } from './errors.js';
 export function serializeCredential(credential) {
     const serialized = {
         accessToken: credential.accessToken,
@@ -78,6 +81,24 @@ export class DBCredentialProvider {
     async delete(providerName, ownerDID) {
         await this.#api.deleteCredential(providerName, ownerDID);
     }
+    async update(address, change) {
+        if (normalizeDID(address.deviceDID) !== this.#api.getLocalDeviceDID()) {
+            throw new CredentialBindNotAuthorized(address.providerName, address.ownerDID);
+        }
+        for(;;){
+            const ref = await this.getVersionedCredentialRef(address.providerName, address.ownerDID);
+            if (ref == null || ref.version == null) throw new CredentialUpdateUnavailableError();
+            const credential = change(ref.credential);
+            const result = await this.setCredentialForEntryIfUnchanged({
+                ...address,
+                entryID: ref.entryID,
+                credential,
+                expectedVersion: ref.version
+            });
+            if (result === 'updated') return;
+            if (result === 'absent') throw new CredentialUpdateUnavailableError();
+        }
+    }
     bindAlias(providerName, ownerDID, entryID) {
         return this.#api.bindAlias(providerName, ownerDID, entryID);
     }
@@ -97,4 +118,22 @@ export class DBCredentialProvider {
             credential: serializeCredential(params.credential)
         });
     }
+    async getVersionedCredentialRef(providerName, ownerDID) {
+        const ref = await this.#api.getVersionedCredentialRef(providerName, ownerDID);
+        if (ref == null) return null;
+        return {
+            credential: deserializeCredential(ref.credential),
+            entryID: ref.entryID,
+            version: ref.version
+        };
+    }
+    async setCredentialForEntryIfUnchanged(params) {
+        return await this.#api.setCredentialForEntryIfUnchanged({
+            providerName: params.providerName,
+            ownerDID: params.ownerDID,
+            entryID: params.entryID,
+            credential: serializeCredential(params.credential),
+            expectedVersion: params.expectedVersion
+        });
+    }
 }

package/lib/record-types.d.ts

@@ -0,0 +1,65 @@
+import { type MethodRegistry } from '@kokuin/token';
+import { type RecordStoreAdapter, type RecordTypeDefinition, type VisibilityContext } from '@kubun/records';
+import { type CredentialStoreAPI } from '@kubun/store-credential';
+export type { CredentialRecordType } from '@kubun/store-credential';
+/**
+ * What the credential record types check against on the receiving device.
+ *
+ * - `store` is the device's credential store. The hooks never read it: every read inside a
+ *   decision goes through the store the decision runs against, since this one is bound
+ *   outside the apply transaction.
+ * - `resolveController` answers the `did:kokuin` controller a device key acts for, or `null`.
+ *   For controller-owned records, only devices at the verifier's current head act for it.
+ * - `verifyAdministerChain` checks, at present time, that `tokens` give `issuer` the
+ *   `credential/administer` right over `owner`.
+ * - `verifyGrantorEnvelope` checks, at present time, that a grantor envelope is valid for the
+ *   wrapping op `wrappingOpHash`, its administer chain included.
+ * - `selfDID` is this device. A wrapping, wrapping authority or manifest is only stored here
+ *   when it is addressed to this device, or when this device acts for the record's owner.
+ */
+export type CredentialRecordTypeDeps = {
+    store: CredentialStoreAPI;
+    resolveController: (did: string) => Promise<string | null>;
+    verifyAdministerChain: (tokens: ReadonlyArray<string>, owner: string, issuer: string) => Promise<boolean>;
+    verifyGrantorEnvelope: (token: string, wrappingOpHash: string) => Promise<boolean>;
+    selfDID: string;
+    methods?: MethodRegistry;
+};
+/** Thrown when a credential hook runs against a store it cannot reach the indexed tables of. */
+export declare class CredentialRecordHookError extends Error {
+    constructor(message: string);
+}
+/**
+ * The id of the entry holding the OAuth grant `name` that `grantDeviceDID` spends for `owner`.
+ * Derived, so the device that may write an entry is a property of the entry's id, whatever
+ * ops a peer has or has not seen for it.
+ */
+export declare function credentialGrantEntryID(owner: string, grantDeviceDID: string, name: string): string;
+/** Revocation removes every indexed wrapping for that recipient, at every key version. */
+export declare function credentialStoreForHooks(adapter: RecordStoreAdapter): CredentialStoreAPI;
+/**
+ * The credential record types, in dependency order: how each merges, who may write it, who
+ * may receive it, what it needs first, and what applying it does to the indexed tables.
+ *
+ * Every authorizer decodes a live payload with the store's codec after checking it against the
+ * signed digest, binds the record to the owner of the key it belongs to, and accepts only an
+ * issuer that acts for that owner. None decrypts or unwraps anything.
+ */
+export declare function credentialRecordTypes(deps: CredentialRecordTypeDeps): ReadonlyMap<string, RecordTypeDefinition>;
+/**
+ * The record types that prove a requester holds a key: wrappings only. A revocation also names
+ * a key and a recipient, and must never pass for a holding.
+ */
+export declare function credentialHolderTypes(types: ReadonlyMap<string, RecordTypeDefinition>): ReadonlyMap<string, RecordTypeDefinition>;
+/**
+ * The responder's current version of a key, for `VisibilityContext.currentKeyVersion`: the
+ * stored key record of that id, when it is live and belongs to `owner`.
+ */
+export declare function credentialKeyVersionReader(store: RecordStoreAdapter, methods?: MethodRegistry): VisibilityContext['currentKeyVersion'];
+/**
+ * The authorizer a responder runs on a holder proof, for `VisibilityContext.authorizeProof`:
+ * the wrapping authorizer apply runs, reading `store`, without the receiver binding — a proof
+ * is the requester's wrapping, never addressed to the responder. Anything but a wrapping, or
+ * a record whose op does not verify, is refused.
+ */
+export declare function credentialProofAuthorizer(deps: CredentialRecordTypeDeps, store: RecordStoreAdapter): VisibilityContext['authorizeProof'];