@kubun/credential 0.17.4 → 0.18.0

package/lib/refreshing-credential-provider.d.ts

@@ -1,5 +1,5 @@
 import type { OAuthProviderDefinition } from '@kokuin/oauth';
-import type { AliasBindingCredentialProvider, Credential, CredentialProvider, EntryPairedCredentialProvider } from '@kubun/credential-types';
+import type { AliasBindingCredentialProvider, Credential, CredentialProvider, EntryPairedCredentialProvider, GrantAddress, VersionedEntryCredentialProvider } from '@kubun/credential-types';
 import type { Logger } from '@kubun/logger';
 import { EventEmitter } from '@sozai/event';
 import type { Runtime } from '@sozai/runtime';
@@ -22,18 +22,20 @@ export type RefreshEvents = {
 export type RefreshOutcome = {
     ok: true;
     credential: Credential;
+    superseded?: boolean;
 } | {
     ok: false;
     category: RefreshFailureCategory;
 };
 export type RefreshingCredentialProviderParams = {
-    inner: CredentialProvider & EntryPairedCredentialProvider & AliasBindingCredentialProvider;
+    inner: InnerCredentialProvider;
     runtime: Runtime;
     providers: Array<OAuthProviderDefinition>;
     bufferSeconds?: number;
     logger?: Logger;
     refreshInFlight?: Map<string, Promise<RefreshOutcome>>;
 };
+type InnerCredentialProvider = CredentialProvider & EntryPairedCredentialProvider & AliasBindingCredentialProvider & Partial<VersionedEntryCredentialProvider>;
 export declare class RefreshingCredentialProvider implements CredentialProvider, AliasBindingCredentialProvider {
     #private;
     constructor(params: RefreshingCredentialProviderParams);
@@ -47,6 +49,8 @@ export declare class RefreshingCredentialProvider implements CredentialProvider,
         ownerWrappableDID?: string;
         controllerWrappableDID?: string;
     }): Promise<void>;
+    update(address: GrantAddress, change: (current: Credential | null) => Credential): Promise<void>;
     delete(providerName: string, ownerDID: string): Promise<void>;
     bindAlias(providerName: string, ownerDID: string, entryID: string): Promise<void>;
 }
+export {};

package/lib/refreshing-credential-provider.js

@@ -1,5 +1,6 @@
 import { OAuthTokenError, refreshToken as requestRefreshedToken } from '@kokuin/oauth';
 import { normalizeDID } from '@kokuin/token';
+import { CredentialUpdateUnavailableError } from '@kubun/credential-types';
 import { EventEmitter } from '@sozai/event';
 const DEFAULT_BUFFER_SECONDS = 300;
 // Wraps a storage-only `CredentialProvider` and adds transparent OAuth refresh on
@@ -38,11 +39,11 @@ export class RefreshingCredentialProvider {
         return this.#inner.get(providerName, ownerDID);
     }
     async get(providerName, ownerDID) {
-        const ref = await this.#inner.getCredentialRef(providerName, ownerDID);
+        const ref = await this.#readRef(providerName, ownerDID);
         if (ref == null) return null;
-        const { credential, entryID } = ref;
+        const { credential, entry } = ref;
         if (this.#isExpiringSoon(credential) && credential.refreshToken != null) {
-            const refreshed = await this.#refresh(providerName, ownerDID, entryID, credential, credential.refreshToken);
+            const refreshed = await this.#refresh(providerName, ownerDID, entry, credential, credential.refreshToken);
             return refreshed ?? credential;
         }
         return credential;
@@ -50,6 +51,10 @@ export class RefreshingCredentialProvider {
     set(params) {
         return this.#inner.set(params);
     }
+    update(address, change) {
+        if (this.#inner.update == null) throw new CredentialUpdateUnavailableError();
+        return this.#inner.update(address, change);
+    }
     delete(providerName, ownerDID) {
         return this.#inner.delete(providerName, ownerDID);
     }
@@ -59,6 +64,28 @@ export class RefreshingCredentialProvider {
     bindAlias(providerName, ownerDID, entryID) {
         return this.#inner.bindAlias(providerName, ownerDID, entryID);
     }
+    async #readRef(providerName, ownerDID) {
+        if (this.#inner.getVersionedCredentialRef != null) {
+            const ref = await this.#inner.getVersionedCredentialRef(providerName, ownerDID);
+            if (ref == null) return null;
+            return {
+                credential: ref.credential,
+                entry: {
+                    entryID: ref.entryID,
+                    version: ref.version
+                }
+            };
+        }
+        const ref = await this.#inner.getCredentialRef(providerName, ownerDID);
+        if (ref == null) return null;
+        return {
+            credential: ref.credential,
+            entry: {
+                entryID: ref.entryID,
+                version: undefined
+            }
+        };
+    }
     #isExpiringSoon(credential) {
         if (credential.expiresAt == null) return false;
         return credential.expiresAt.getTime() - Date.now() < this.#bufferMs;
@@ -74,18 +101,18 @@ export class RefreshingCredentialProvider {
     // `get`). Followers await the coordinator's promise and reuse its outcome for
     // their own stale-fallback decision without emitting a second event. The key is
     // normalized so the two `did:peer:4` spellings of one owner share an entry.
-    async #refresh(providerName, ownerDID, entryID, credential, refreshToken) {
+    async #refresh(providerName, ownerDID, entry, credential, refreshToken) {
         // entryID is part of the key: a caller that read a DIFFERENT entry (a
         // delete+rebind landed between its read and this one) must never join an
         // in-flight exchange started against the old entry and receive its
         // refreshed credential.
-        const key = `${providerName}:${normalizeDID(ownerDID)}:${entryID}`;
+        const key = `${providerName}:${normalizeDID(ownerDID)}:${entry.entryID}`;
         const inFlight = this.#refreshInFlight.get(key);
         if (inFlight != null) {
             const outcome = await inFlight;
             return outcome.ok ? outcome.credential : null;
         }
-        const exchange = this.#exchange(providerName, ownerDID, entryID, credential, refreshToken);
+        const exchange = this.#exchange(providerName, ownerDID, entry, credential, refreshToken);
         this.#refreshInFlight.set(key, exchange);
         let outcome;
         try {
@@ -94,6 +121,9 @@ export class RefreshingCredentialProvider {
             this.#refreshInFlight.delete(key);
         }
         if (outcome.ok) {
+            // A superseded exchange refreshed nothing that was kept: whoever replaced
+            // the stored credential reports its own outcome.
+            if (outcome.superseded) return outcome.credential;
             this.#events.fire('refreshed', {
                 providerName,
                 ownerDID,
@@ -113,7 +143,7 @@ export class RefreshingCredentialProvider {
     // one provider+owner never reach here twice: `#refresh` shares a single pending
     // `#exchange` promise through the single-flight map. Returns a discriminated
     // outcome and does not emit or fall back itself.
-    async #exchange(providerName, ownerDID, entryID, credential, refreshToken) {
+    async #exchange(providerName, ownerDID, entry, credential, refreshToken) {
         const provider = this.#providers.find((p)=>p.name === providerName);
         if (provider == null) {
             return {
@@ -151,12 +181,7 @@ export class RefreshingCredentialProvider {
         };
         let write;
         try {
-            write = await this.#inner.setCredentialForEntry({
-                providerName,
-                ownerDID,
-                entryID,
-                credential: refreshed
-            });
+            write = await this.#writeBack(providerName, ownerDID, entry, refreshed);
         } catch  {
             // A rotated refresh token (the endpoint issued a new one) means the prior
             // token may already be invalidated server-side, so a lost write here
@@ -180,9 +205,47 @@ export class RefreshingCredentialProvider {
                 category: 'stale'
             };
         }
+        // The entry was written since this refresh read it (a consent landed
+        // mid-exchange): that write was kept, so hand back what is stored now. A
+        // failed reread falls back to the credential this refresh started from.
+        if (write === 'superseded') {
+            let current = null;
+            try {
+                current = (await this.#readRef(providerName, ownerDID))?.credential ?? null;
+            } catch  {
+            // Fall back below: the write-back itself succeeded as a no-op.
+            }
+            return {
+                ok: true,
+                credential: current ?? credential,
+                superseded: true
+            };
+        }
         return {
             ok: true,
             credential: refreshed
         };
     }
+    // Writes a refreshed credential back to the exact entry the refresh read. With
+    // a version it is conditional too: the store checks and writes in one call, so
+    // a consent that replaced the entry mid-exchange is never overwritten and no
+    // lock has to span the exchange or the consent's transaction.
+    #writeBack(providerName, ownerDID, entry, credential) {
+        const { entryID, version } = entry;
+        if (version != null && this.#inner.setCredentialForEntryIfUnchanged != null) {
+            return this.#inner.setCredentialForEntryIfUnchanged({
+                providerName,
+                ownerDID,
+                entryID,
+                credential,
+                expectedVersion: version
+            });
+        }
+        return this.#inner.setCredentialForEntry({
+            providerName,
+            ownerDID,
+            entryID,
+            credential
+        });
+    }
 }

package/lib/suite.d.ts

@@ -44,10 +44,7 @@ export type CredentialSuite = {
     generateContentKey(runtime: Runtime): Uint8Array;
     wrap(params: WrapParams): Promise<WrapResult>;
     unwrap(params: UnwrapParams): Promise<Uint8Array>;
-    encryptEntry(params: EncryptEntryParams): {
-        iv: Uint8Array;
-        ciphertext: Uint8Array;
-    };
+    encryptEntry(params: EncryptEntryParams): EncryptEntryResult;
     decryptEntry(params: DecryptEntryParams): Uint8Array;
 };
 export type WrapParams = {
@@ -64,6 +61,10 @@ export type WrapParams = {
      */
     methods?: MethodRegistry;
 };
+export type EncryptEntryResult = {
+    iv: Uint8Array;
+    ciphertext: Uint8Array;
+};
 export type WrapResult = {
     descriptors: Array<CredentialFactorDescriptor>;
     iv: Uint8Array;

package/lib/suite.js

@@ -239,8 +239,8 @@ const suite1 = {
         };
     },
     async unwrap (params) {
-        // Validated on open too, not only on create: wrappings arrive off the wire
-        // (`credential:key-grant`), and a pin-only wrapping is openable by anyone who
+        // Validated on open too, not only on create: wrappings arrive from peers,
+        // and a pin-only wrapping is openable by anyone who
         // guesses four digits, a factorless one by anyone at all. A wrapping this
         // build refuses to make is not one it agrees to open.
         validateFactorList(params.descriptors.map((descriptor)=>descriptor.kind));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/credential",
-  "version": "0.17.4",
+  "version": "0.18.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -17,25 +17,26 @@
   "dependencies": {
     "@kokuin/jwe": "^0.1.0",
     "@kokuin/oauth": "^0.1.1",
-    "@kokuin/token": "^0.5.0",
-    "@kubun/credential-types": "^0.17.2",
-    "@kubun/db": "^0.17.0",
-    "@kubun/hlc": "^0.17.0",
-    "@kubun/id": "^0.17.0",
-    "@kubun/logger": "^0.17.0",
-    "@kubun/store-credential": "^0.17.4",
+    "@kokuin/token": "^0.5.1",
+    "@kubun/credential-types": "^0.18.0",
+    "@kubun/db": "^0.18.0",
+    "@kubun/hlc": "^0.18.0",
+    "@kubun/id": "^0.18.0",
+    "@kubun/logger": "^0.18.0",
+    "@kubun/records": "^0.18.0",
+    "@kubun/store-credential": "^0.18.0",
     "@noble/ciphers": "^2.4.0",
     "@noble/hashes": "^2.4.0",
-    "@sozai/codec": "^0.4.0",
-    "@sozai/event": "^0.1.3",
+    "@sozai/codec": "^0.4.3",
+    "@sozai/event": "^0.1.6",
     "@sozai/runtime": "^0.1.0"
   },
   "devDependencies": {
-    "@kubun/db-adapter": "^0.17.0",
-    "@kubun/db-better-sqlite": "^0.17.0",
-    "@kubun/db-postgres": "^0.17.1",
-    "@testcontainers/postgresql": "^12.1.0",
-    "kysely": "^0.29.6"
+    "@kubun/db-adapter": "^0.18.0",
+    "@kubun/db-better-sqlite": "^0.18.0",
+    "@kubun/db-postgres": "^0.18.0",
+    "@testcontainers/postgresql": "^12.2.1",
+    "kysely": "^0.29.7"
   },
   "publishConfig": {
     "access": "public"

package/lib/op.d.ts

@@ -1,128 +0,0 @@
-import { type SigningIdentity } from '@kokuin/token';
-import type { CredentialEntry, CredentialKey, CredentialOpInput, CredentialOpSubjectKind, CredentialTombstoneInput, CredentialWrapping, PutCredentialEntryParams, PutCredentialKeyParams, PutCredentialWrappingParams } from '@kubun/store-credential';
-/**
- * What the author of a credential row signs.
- *
- * Digests rather than bytes, as a grant token does: an op travels beside the row
- * it speaks for, so repeating the ciphertext in the signature would double every
- * vault on the wire.
- *
- * `contentDigest` is `null` exactly when `deleted` — a tombstone has no content,
- * and a digest of nothing would be a constant every tombstone shared.
- */
-export type CredentialOpClaim = {
-    subjectKind: CredentialOpSubjectKind;
-    subjectID: string;
-    keyID: string;
-    keyVersion: number;
-    hlc: string;
-    contentDigest: string | null;
-    deleted: boolean;
-    /**
-     * The content-key branch a wrapping or entry joins: its introducing key-op's
-     * `${hlc}:${opHash}` label, signed so a relay cannot move a row between
-     * branches. Absent on a key-op — a key-op's own label folds its own `opHash`,
-     * which is unknown until after signing, so it is recomputed on receipt rather
-     * than claimed. Absent too on an op minted outside a rotation/create, which
-     * does not yet resolve its branch.
-     */
-    branchID?: string;
-};
-/** `issuer` is the normalized verified `iss` — the only author claim a receiver trusts. */
-export type VerifiedCredentialOp = {
-    issuer: string;
-    claim: CredentialOpClaim;
-};
-/** Which row an op speaks for, for the ops that carry no row of their own. */
-export type CredentialOpSubject = {
-    subjectKind: CredentialOpSubjectKind;
-    subjectID: string;
-    keyID: string;
-    keyVersion: number;
-};
-/** A stored row, tagged with which of the three tables it came from. */
-export type CredentialRowSubject = {
-    kind: 'key';
-    row: CredentialKey;
-} | {
-    kind: 'wrapping';
-    row: CredentialWrapping;
-} | {
-    kind: 'entry';
-    row: CredentialEntry;
-};
-/**
- * A row about to be written, in the shape the store takes it.
- *
- * The counterpart to {@link CredentialRowSubject} for a caller that holds no row
- * yet — a receiver checking an op against bytes it has not stored. It is also
- * the shape the signer signs, so the two sides compare the same fields.
- */
-export type CredentialPutSubject = {
-    kind: 'key';
-    params: PutCredentialKeyParams;
-} | {
-    kind: 'wrapping';
-    params: PutCredentialWrappingParams;
-} | {
-    kind: 'entry';
-    params: PutCredentialEntryParams;
-};
-/**
- * Mints the signed op for every credential row this device writes.
- *
- * Separate from the store because the store holds no identity and does no
- * crypto: it takes the token as opaque text, exactly as it takes a ciphertext.
- */
-export type CredentialOpSigner = {
-    key(params: PutCredentialKeyParams, hlc: string): Promise<CredentialOpInput>;
-    /**
-     * `branchID` is the introducing key-op's label — passed by a create/rotate
-     * that just minted that key-op. Omitted elsewhere: an op made outside a
-     * rotation does not yet resolve its branch, and gets an empty label until a
-     * later slice threads the current one out of the read path.
-     */
-    wrapping(params: PutCredentialWrappingParams, hlc: string, branchID?: string): Promise<CredentialOpInput>;
-    /**
-     * Stamped from the entry's own `hlc`, never a second reading of the clock. The
-     * entry row keeps that column and the op repeats it, so the two would
-     * otherwise disagree the moment the clock moved between them. `branchID` as on
-     * {@link CredentialOpSigner.wrapping}.
-     */
-    entry(params: PutCredentialEntryParams, branchID?: string): Promise<CredentialOpInput>;
-    tombstone(subject: CredentialOpSubject, hlc: string): Promise<CredentialOpInput>;
-    /** A tombstone naming its own subject, for a delete that removes several rows. */
-    wrappingTombstone(subject: CredentialOpSubject, hlc: string): Promise<CredentialTombstoneInput>;
-};
-/** The digest of the bytes a row holds, per subject kind. */
-export declare function credentialRowDigest(subject: CredentialRowSubject): string;
-/** The digest of the bytes a row is about to be written with, per subject kind. */
-export declare function credentialPutDigest(subject: CredentialPutSubject): string;
-/** Whether a verified claim speaks for a stored row. */
-export declare function credentialOpMatchesRow(claim: CredentialOpClaim, subject: CredentialRowSubject): boolean;
-/** Whether a verified claim speaks for a row about to be written. */
-export declare function credentialOpMatchesPut(claim: CredentialOpClaim, subject: CredentialPutSubject): boolean;
-export declare function createCredentialOpSigner(identity: SigningIdentity): CredentialOpSigner;
-/**
- * Order two branch labels, keyless and total.
- *
- * The `hlc` halves are compared as strings: the serialized HLC form is
- * lexically total-ordered by construction (fixed-width ISO wall time, then a
- * zero-padded counter, then the nodeID), the same property the store's
- * tombstone check leans on. Two concurrent rotations neither dominate, so the
- * `opHash` breaks the tie — also lexical, and distinct per op, which is what
- * makes the order total and identical on every device.
- */
-export declare function compareBranchIDs(a: string, b: string): number;
-/**
- * The single branch a keyless party names as the winner: the one whose
- * introducing key-op dominates by HLC, `opHash` breaking genuine concurrency.
- * Order-independent — every device folds the same set to the same label.
- */
-export declare function selectWinningBranch(branchIDs: ReadonlyArray<string>): string;
-/**
- * Verify an op and extract its claim. Returns `null` (never throws) when the
- * token is unparseable, unsigned (`alg: 'none'`), or structurally malformed — an
- * attacker cannot forge an `iss` this way.
- */
-export declare function verifyCredentialOp(token: string): Promise<VerifiedCredentialOp | null>;