@kubun/credential 0.17.0 → 0.17.2

package/lib/api.d.ts

@@ -37,6 +37,19 @@ export type CredentialAPI = {
         credential: string;
     }) => Promise<void>;
     deleteCredential: (providerName: string, ownerDID: string) => Promise<void>;
+    /**
+     * Point `(providerName, ownerDID)` at an entry this device already holds,
+     * without minting anything.
+     *
+     * Gate B first: the entry's key must be owned by `ownerDID` (normalized on
+     * both sides), because the vault can decrypt any entry it holds a server
+     * wrapping for — decryptability is not authority. An idempotent retry that
+     * already points at `entryID` returns before that entry is ever decrypted, so
+     * a safe retry cannot fail on a branch/version check inside the read. Only
+     * then is the decrypted plaintext checked against the `Credential` shape, so a
+     * malformed or mistyped entry can never become a resolvable alias.
+     */
+    bindAlias: (providerName: string, ownerDID: string, entryID: string) => Promise<void>;
     /**
      * The normalized owner DIDs that currently hold a credential for `providerName`.
      *
@@ -54,6 +67,26 @@ export type CredentialAPI = {
      * agreement key is resolvable only through the controller resolver.
      */
     getControllerMethods: () => MethodRegistry;
+    /**
+     * Like `getCredential`, but pairs the serialized credential with the entryID
+     * it resolved through the alias — so a caller can then target that entry
+     * directly (e.g. `setCredentialForEntry`) without re-resolving the alias.
+     */
+    getCredentialRef: (providerName: string, ownerDID: string) => Promise<{
+        credential: string;
+        entryID: string;
+    } | null>;
+    /**
+     * Write to a specific entry, not the alias — the counterpart to
+     * `getCredentialRef`. Presence-gated on the entry itself (via
+     * `manager.updateEntryIfPresent`), so it never resurrects a deleted entry.
+     */
+    setCredentialForEntry: (params: {
+        providerName: string;
+        ownerDID: string;
+        entryID: string;
+        credential: string;
+    }) => Promise<'updated' | 'absent'>;
 };
 export type CreateCredentialAPIParams = {
     stores: StoreProvider;

package/lib/api.js

@@ -1,7 +1,8 @@
 import { normalizeDID } from '@kokuin/token';
 import { getCredentialStore } from '@kubun/store-credential';
 import { fromUTF, toUTF } from '@sozai/codec';
-import { CredentialSupersededBranch } from './errors.js';
+import { CredentialAliasAlreadyBound, CredentialBindNotAuthorized, CredentialEntryAlreadyAliased, CredentialInvalidEntry, CredentialNotFound, CredentialSupersededBranch } from './errors.js';
+import { assertValidCredentialShape } from './validate.js';
 export function createCredentialAPI(params) {
     const getAliasStore = ()=>getCredentialStore(params.stores);
     const getCredentials = ()=>params.getCredentialManager(params.stores);
@@ -13,8 +14,13 @@ export function createCredentialAPI(params) {
             const store = await getAliasStore();
             const entryID = await store.getAliasEntryID(providerName, normalizeDID(ownerDID));
             if (entryID == null) return null;
+            // A dangling alias (its entry was deleted out from under it) resolves to null,
+            // not an error: a missing ENTRY is checked structurally here so a missing KEY
+            // inside readEntry still surfaces as CredentialNotFound below.
+            if (await store.getEntry(entryID) == null) return null;
             try {
-                return toUTF(await (await getCredentials()).readEntry(entryID));
+                const credentials = await getCredentials();
+                return toUTF(await credentials.readEntry(entryID));
             } catch (error) {
                 if (error instanceof CredentialSupersededBranch) {
                     params.logger.warn('Credential entry {entryID} for provider {providerName} belongs to a superseded branch', {
@@ -44,7 +50,8 @@ export function createCredentialAPI(params) {
             // Opens the key through the server's own wrapping and rewrites the entry
             // under it. No key is minted and no wrapping is touched, so a refresh
             // cannot change who can read the credential.
-            await (await getCredentials()).updateEntry(entryID, fromUTF(credential));
+            const credentials = await getCredentials();
+            await credentials.updateEntry(entryID, fromUTF(credential));
         },
         async createCredential (input) {
             const { providerName, ownerDID, ownerWrappableDID, credential } = input;
@@ -113,15 +120,104 @@ export function createCredentialAPI(params) {
             const store = await getAliasStore();
             const owner = normalizeDID(ownerDID);
             const entryID = await store.getAliasEntryID(providerName, owner);
-            await store.deleteAliasEntryID(providerName, owner);
-            if (entryID != null) {
-                // The pointer and the entry go together. Leaving the entry would keep
-                // the token readable by anyone who kept its id after a disconnect.
-                await (await getCredentials()).deleteEntry(entryID);
+            // Entry first, THEN the pointer. This ordering keeps a concurrent bindAlias
+            // from leaving a dangling alias: once the entry is gone, bindAliasIfAbsent's
+            // entry-existence-conditioned insert refuses (there is no row to point at),
+            // so no new alias can be installed against the entry being removed. The brief
+            // window where the old pointer outlives its entry is covered by getCredential/
+            // getCredentialRef, which treat a missing entry as null. The pointer and the
+            // entry still go together — leaving the entry would keep the token readable by
+            // anyone who kept its id after a disconnect.
+            // No pointer to delete: there is nothing of ours to remove. An unconditional
+            // clear here would only drop an alias a concurrent bindAlias installed between
+            // the read above and now, so leave the slot untouched.
+            if (entryID == null) return;
+            const credentials = await getCredentials();
+            await credentials.deleteEntry(entryID);
+            // Clear the pointer ONLY while it still names the entry we removed. A concurrent
+            // bindAlias can repair a briefly-dangling pointer onto a fresh entry in the gap
+            // after deleteEntry; an unconditional delete would drop that valid new binding.
+            // If the pointer already moved, leave it.
+            await store.deleteAliasIfEntry(providerName, owner, entryID);
+        },
+        async bindAlias (providerName, ownerDID, entryID) {
+            const owner = normalizeDID(ownerDID);
+            const credentials = await getCredentials();
+            // Gate B: the acting subject must own the entry's key. The vault can
+            // decrypt any entry it holds a server wrapping for, so decryptability is
+            // not authority.
+            const keyOwner = await credentials.getEntryKeyOwnerDID(entryID);
+            if (keyOwner == null) {
+                throw new CredentialNotFound('Credential entry', entryID);
+            }
+            if (normalizeDID(keyOwner) !== owner) {
+                throw new CredentialBindNotAuthorized(providerName, ownerDID);
+            }
+            const store = await getAliasStore();
+            // Idempotent short-circuit BEFORE decrypt, so a safe retry cannot fail on
+            // a branch/version check inside readEntry.
+            if (await store.getAliasEntryID(providerName, owner) === entryID) {
+                return;
             }
+            // Validate the decrypted plaintext is actually a credential before it can
+            // ever be resolved back out through getCredential.
+            const bytes = await credentials.readEntry(entryID);
+            let parsed;
+            try {
+                parsed = JSON.parse(toUTF(bytes));
+            } catch (cause) {
+                throw new CredentialInvalidEntry('credential entry is not valid JSON', {
+                    cause
+                });
+            }
+            assertValidCredentialShape(parsed);
+            const result = await store.bindAliasIfAbsent({
+                namespace: providerName,
+                aliasKey: owner,
+                entryID
+            });
+            if (result === 'inserted') return;
+            if (result === 'entry-missing') {
+                throw new CredentialNotFound('Credential entry', entryID);
+            }
+            if (result.conflict === 'alias') {
+                if (result.existing === entryID) return; // concurrent idempotent retry
+                throw new CredentialAliasAlreadyBound(providerName, ownerDID);
+            }
+            throw new CredentialEntryAlreadyAliased(providerName, entryID) // conflict: 'entry'
+            ;
         },
         getControllerMethods () {
             return params.getControllerMethods(params.stores);
+        },
+        async getCredentialRef (providerName, ownerDID) {
+            const store = await getAliasStore();
+            const entryID = await store.getAliasEntryID(providerName, normalizeDID(ownerDID));
+            if (entryID == null) return null;
+            // Dangling alias → null, checked structurally (see getCredential): a missing
+            // entry is not an error, a missing key inside readEntry still throws.
+            if (await store.getEntry(entryID) == null) return null;
+            try {
+                const credentials = await getCredentials();
+                const bytes = await credentials.readEntry(entryID);
+                return {
+                    credential: toUTF(bytes),
+                    entryID
+                };
+            } catch (error) {
+                if (error instanceof CredentialSupersededBranch) {
+                    params.logger.warn('Credential entry {entryID} for provider {providerName} belongs to a superseded branch', {
+                        providerName,
+                        entryID
+                    });
+                    return null;
+                }
+                throw error;
+            }
+        },
+        async setCredentialForEntry (params) {
+            const credentials = await getCredentials();
+            return await credentials.updateEntryIfPresent(params.entryID, fromUTF(params.credential));
         }
     };
 }

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_ERROR' | 'CREDENTIAL_FACTOR_UNAVAILABLE' | 'CREDENTIAL_FACTORS_INVALID' | '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_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 CredentialErrorOptions = ErrorOptions & {
     code: CredentialErrorCode;
 };
@@ -167,3 +167,52 @@ export declare class CredentialUnopenable extends CredentialError {
     constructor(keyID: string, reason: string);
     get keyID(): string;
 }
+/**
+ * The caller is not the entry's key owner, so the alias bind is refused.
+ *
+ * Distinct from the existing {@link CredentialNotAuthorized}, which is a
+ * verb-scoped key-authority check (`'read' | 'administer'` against a keyID).
+ * This is an owner-identity check on a (providerName, ownerDID) pair ahead of
+ * the bind-alias seam's Gate B, not a key authority the device may hold —
+ * widening `CredentialAuthorization` to cover it would let this check feed
+ * `CredentialAuthority.authorize`, which it must not.
+ */
+export declare class CredentialBindNotAuthorized extends CredentialError {
+    constructor(providerName: string, ownerDID: string);
+}
+/**
+ * A provider/owner alias already points at a different entry.
+ *
+ * `UNIQUE(namespace, alias_key)` in the alias table enforces this; the bind
+ * seam classifies the conflicting read-back into this error rather than
+ * silently overwriting the existing binding.
+ */
+export declare class CredentialAliasAlreadyBound extends CredentialError {
+    #private;
+    constructor(providerName: string, ownerDID: string);
+    get providerName(): string;
+    get ownerDID(): string;
+}
+/**
+ * An entry already holds an alias, and this bind would give it a second one.
+ *
+ * `UNIQUE(entry_id)` in the alias table enforces one-alias-per-entry; the bind
+ * seam classifies the conflicting read-back into this error rather than
+ * attaching a second provider name to the same entry.
+ */
+export declare class CredentialEntryAlreadyAliased extends CredentialError {
+    #private;
+    constructor(providerName: string, entryID: string);
+    get providerName(): string;
+    get entryID(): string;
+}
+/**
+ * Decrypted entry bytes do not match the `Credential` shape.
+ *
+ * Bind and refresh decrypt arbitrary stored bytes; without this check a
+ * malformed or mistyped entry (`{}`, a non-string `accessToken`) would be
+ * trusted as a credential instead of refused at the boundary.
+ */
+export declare class CredentialInvalidEntry extends CredentialError {
+    constructor(message: string, options?: ErrorOptions);
+}

package/lib/errors.js

@@ -246,3 +246,83 @@
         return this.#keyID;
     }
 }
+/**
+ * The caller is not the entry's key owner, so the alias bind is refused.
+ *
+ * Distinct from the existing {@link CredentialNotAuthorized}, which is a
+ * verb-scoped key-authority check (`'read' | 'administer'` against a keyID).
+ * This is an owner-identity check on a (providerName, ownerDID) pair ahead of
+ * the bind-alias seam's Gate B, not a key authority the device may hold —
+ * widening `CredentialAuthorization` to cover it would let this check feed
+ * `CredentialAuthority.authorize`, which it must not.
+ */ export class CredentialBindNotAuthorized extends CredentialError {
+    constructor(providerName, ownerDID){
+        super(`Not authorized to bind ${providerName} alias for ${ownerDID}`, {
+            code: 'CREDENTIAL_BIND_NOT_AUTHORIZED'
+        });
+        this.name = 'CredentialBindNotAuthorized';
+    }
+}
+/**
+ * A provider/owner alias already points at a different entry.
+ *
+ * `UNIQUE(namespace, alias_key)` in the alias table enforces this; the bind
+ * seam classifies the conflicting read-back into this error rather than
+ * silently overwriting the existing binding.
+ */ export class CredentialAliasAlreadyBound extends CredentialError {
+    #providerName;
+    #ownerDID;
+    constructor(providerName, ownerDID){
+        super(`Alias ${providerName} for ${ownerDID} is already bound to a different credential entry`, {
+            code: 'CREDENTIAL_ALIAS_ALREADY_BOUND'
+        });
+        this.name = 'CredentialAliasAlreadyBound';
+        this.#providerName = providerName;
+        this.#ownerDID = ownerDID;
+    }
+    get providerName() {
+        return this.#providerName;
+    }
+    get ownerDID() {
+        return this.#ownerDID;
+    }
+}
+/**
+ * An entry already holds an alias, and this bind would give it a second one.
+ *
+ * `UNIQUE(entry_id)` in the alias table enforces one-alias-per-entry; the bind
+ * seam classifies the conflicting read-back into this error rather than
+ * attaching a second provider name to the same entry.
+ */ export class CredentialEntryAlreadyAliased extends CredentialError {
+    #providerName;
+    #entryID;
+    constructor(providerName, entryID){
+        super(`Credential entry ${entryID} is already aliased; cannot bind it under ${providerName}`, {
+            code: 'CREDENTIAL_ENTRY_ALREADY_ALIASED'
+        });
+        this.name = 'CredentialEntryAlreadyAliased';
+        this.#providerName = providerName;
+        this.#entryID = entryID;
+    }
+    get providerName() {
+        return this.#providerName;
+    }
+    get entryID() {
+        return this.#entryID;
+    }
+}
+/**
+ * Decrypted entry bytes do not match the `Credential` shape.
+ *
+ * Bind and refresh decrypt arbitrary stored bytes; without this check a
+ * malformed or mistyped entry (`{}`, a non-string `accessToken`) would be
+ * trusted as a credential instead of refused at the boundary.
+ */ export class CredentialInvalidEntry extends CredentialError {
+    constructor(message, options){
+        super(message, {
+            ...options,
+            code: 'CREDENTIAL_INVALID_ENTRY'
+        });
+        this.name = 'CredentialInvalidEntry';
+    }
+}

package/lib/index.d.ts

@@ -7,7 +7,7 @@ export { buildCredentialEntry, buildCredentialKey } from './builder.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, CredentialError, CredentialKeyLocked, CredentialKeyVersionMismatch, CredentialNotAuthorized, CredentialNotFound, CredentialPinRejected, CredentialSecretRejected, CredentialSupersededBranch, CredentialTampered, CredentialUnopenable, InvalidCredentialFactors, NoAvailableFactor, UnsupportedCredentialSuite, } 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 { createCredentialManager } from './manager.js';
 export type { CredentialOpClaim, CredentialOpSigner, CredentialOpSubject, CredentialPutSubject, CredentialRowSubject, VerifiedCredentialOp, } from './op.js';
@@ -22,4 +22,5 @@ export type { RefreshEvents, RefreshedEvent, RefreshFailedEvent, RefreshFailureC
 export { RefreshingCredentialProvider } from './refreshing-credential-provider.js';
 export type { Argon2Cost, CredentialSuite, 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

@@ -2,7 +2,7 @@ export { createCredentialAPI } from './api.js';
 export { createDeviceAuthority } from './authority.js';
 export { buildCredentialEntry, buildCredentialKey } from './builder.js';
 export { credentialEntriesDigest, credentialEntryDigest, credentialKeyDigest, credentialWrappingDigest, digestParts } from './digest.js';
-export { AmbiguousCredentialWrapping, CredentialError, CredentialKeyLocked, CredentialKeyVersionMismatch, CredentialNotAuthorized, CredentialNotFound, CredentialPinRejected, CredentialSecretRejected, CredentialSupersededBranch, CredentialTampered, CredentialUnopenable, InvalidCredentialFactors, NoAvailableFactor, UnsupportedCredentialSuite } 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 { createCredentialManager } from './manager.js';
 export { compareBranchIDs, createCredentialOpSigner, credentialOpMatchesPut, credentialOpMatchesRow, credentialPutDigest, credentialRowDigest, selectWinningBranch, verifyCredentialOp } from './op.js';
 export { createPinThrottle, DEFAULT_BASE_DELAY, DEFAULT_FREE_ATTEMPTS, DEFAULT_MAX_DELAY } from './pin-throttle.js';
@@ -10,4 +10,5 @@ export { entryProvenanceFields } from './provenance.js';
 export { DBCredentialProvider, deserializeCredential, serializeCredential } from './provider.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';
 export { CREDENTIAL_ADMINISTER_ACTION, credentialUserResource } from './vocabulary.js';

package/lib/manager.d.ts

@@ -257,8 +257,22 @@ export type CredentialManager = {
     deleteKey(keyID: string): Promise<void>;
     putEntry(keyID: string, plaintext: Uint8Array): Promise<string>;
     updateEntry(entryID: string, plaintext: Uint8Array): Promise<void>;
+    /**
+     * As {@link updateEntry}, but never inserts: an entry gone by the time the
+     * write lands reports `'absent'` instead of raising. For a writeback racing a
+     * concurrent delete, where the caller has no `keyID` to fall back to `putEntry`
+     * with and raising would just be a `catch` the caller re-swallows.
+     */
+    updateEntryIfPresent(entryID: string, plaintext: Uint8Array): Promise<'updated' | 'absent'>;
     readEntry(entryID: string): Promise<Uint8Array>;
     getEntryProvenance(entryID: string): Promise<CredentialEntryProvenance>;
+    /**
+     * The RAW `owner_did` off the entry's key row — never normalized. Callers
+     * comparing against another DID normalize it themselves; folding it here
+     * would make the answer wrong for whichever caller wanted the unfolded form.
+     * `null` when the entry, or the key it sits on, is absent.
+     */
+    getEntryKeyOwnerDID(entryID: string): Promise<string | null>;
     listEntries(keyID: string): Promise<Array<string>>;
     deleteEntry(entryID: string): Promise<void>;
     /**

package/lib/manager.js

@@ -898,6 +898,43 @@ export function createCredentialManager(params) {
             };
             await store.putEntry(updated, await ops.entry(updated, branchID));
         },
+        async updateEntryIfPresent (entryID, plaintext) {
+            const existing = await store.getEntry(entryID);
+            if (existing == null) {
+                return 'absent';
+            }
+            const { contentKey, version, branchID } = await openKey(existing.key_id);
+            // Same re-encrypt-under-current-version shape as `updateEntry`: the suite
+            // lookup's store read stays inside the `try` so a rejection cannot leak the
+            // key copy.
+            let encrypted;
+            try {
+                const suite = getSuite((await store.getKey(existing.key_id))?.suite ?? SUITE_KUBUN_CRED_1);
+                encrypted = suite.encryptEntry({
+                    runtime,
+                    contentKey,
+                    plaintext,
+                    keyID: existing.key_id,
+                    keyVersion: version,
+                    entryID
+                });
+            } finally{
+                contentKey.fill(0);
+            }
+            const { iv, ciphertext } = encrypted;
+            const updated = {
+                entryID,
+                keyID: existing.key_id,
+                keyVersion: version,
+                iv,
+                ciphertext,
+                // A fresh stamp every time, not `existing.hlc` carried forward: the store
+                // primitive is op-first and gates the row write on this op winning LWW, so
+                // the writeback needs a current stamp to land at all.
+                hlc: await nextHLC()
+            };
+            return await store.updateEntryIfPresent(updated, await ops.entry(updated, branchID));
+        },
         async readEntry (entryID) {
             const entry = await store.getEntry(entryID);
             if (entry == null) {
@@ -943,6 +980,14 @@ export function createCredentialManager(params) {
             }
             return entryProvenanceFields(entry);
         },
+        async getEntryKeyOwnerDID (entryID) {
+            const entry = await store.getEntry(entryID);
+            if (entry == null) {
+                return null;
+            }
+            const key = await store.getKey(entry.key_id);
+            return key == null ? null : key.owner_did;
+        },
         async listEntries (keyID) {
             return (await store.listEntries(keyID)).map((entry)=>entry.entry_id);
         },

package/lib/provider.d.ts

@@ -1,11 +1,11 @@
-import type { Credential, CredentialProvider } from '@kubun/credential-types';
+import type { AliasBindingCredentialProvider, Credential, CredentialProvider, EntryPairedCredentialProvider } 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 {
+export declare class DBCredentialProvider implements CredentialProvider, AliasBindingCredentialProvider, EntryPairedCredentialProvider {
     #private;
     constructor(params: DBCredentialProviderParams);
     get(providerName: string, ownerDID: string): Promise<Credential | null>;
@@ -17,4 +17,15 @@ export declare class DBCredentialProvider implements CredentialProvider {
         controllerWrappableDID?: string;
     }): Promise<void>;
     delete(providerName: string, ownerDID: string): Promise<void>;
+    bindAlias(providerName: string, ownerDID: string, entryID: string): Promise<void>;
+    getCredentialRef(providerName: string, ownerDID: string): Promise<{
+        credential: Credential;
+        entryID: string;
+    } | null>;
+    setCredentialForEntry(params: {
+        providerName: string;
+        ownerDID: string;
+        entryID: string;
+        credential: Credential;
+    }): Promise<'updated' | 'absent'>;
 }

package/lib/provider.js

@@ -72,4 +72,23 @@ export class DBCredentialProvider {
     async delete(providerName, ownerDID) {
         await this.#api.deleteCredential(providerName, ownerDID);
     }
+    bindAlias(providerName, ownerDID, entryID) {
+        return this.#api.bindAlias(providerName, ownerDID, entryID);
+    }
+    async getCredentialRef(providerName, ownerDID) {
+        const ref = await this.#api.getCredentialRef(providerName, ownerDID);
+        if (ref == null) return null;
+        return {
+            credential: deserializeCredential(ref.credential),
+            entryID: ref.entryID
+        };
+    }
+    async setCredentialForEntry(params) {
+        return await this.#api.setCredentialForEntry({
+            providerName: params.providerName,
+            ownerDID: params.ownerDID,
+            entryID: params.entryID,
+            credential: serializeCredential(params.credential)
+        });
+    }
 }

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

@@ -1,9 +1,9 @@
 import type { OAuthProviderDefinition } from '@kokuin/oauth';
-import type { Credential, CredentialProvider } from '@kubun/credential-types';
+import type { AliasBindingCredentialProvider, Credential, CredentialProvider, EntryPairedCredentialProvider } from '@kubun/credential-types';
 import type { Logger } from '@kubun/logger';
 import { EventEmitter } from '@sozai/event';
 import type { Runtime } from '@sozai/runtime';
-export type RefreshFailureCategory = 'invalid_grant' | 'transient' | 'configuration' | 'persistence';
+export type RefreshFailureCategory = 'invalid_grant' | 'transient' | 'configuration' | 'persistence' | 'stale';
 export type RefreshedEvent = {
     providerName: string;
     ownerDID: string;
@@ -27,14 +27,14 @@ export type RefreshOutcome = {
     category: RefreshFailureCategory;
 };
 export type RefreshingCredentialProviderParams = {
-    inner: CredentialProvider;
+    inner: CredentialProvider & EntryPairedCredentialProvider & AliasBindingCredentialProvider;
     runtime: Runtime;
     providers: Array<OAuthProviderDefinition>;
     bufferSeconds?: number;
     logger?: Logger;
     refreshInFlight?: Map<string, Promise<RefreshOutcome>>;
 };
-export declare class RefreshingCredentialProvider implements CredentialProvider {
+export declare class RefreshingCredentialProvider implements CredentialProvider, AliasBindingCredentialProvider {
     #private;
     constructor(params: RefreshingCredentialProviderParams);
     get refreshEvents(): EventEmitter<RefreshEvents>;
@@ -48,4 +48,5 @@ export declare class RefreshingCredentialProvider implements CredentialProvider
         controllerWrappableDID?: string;
     }): Promise<void>;
     delete(providerName: string, ownerDID: string): Promise<void>;
+    bindAlias(providerName: string, ownerDID: string, entryID: string): Promise<void>;
 }

package/lib/refreshing-credential-provider.js

@@ -38,10 +38,11 @@ export class RefreshingCredentialProvider {
         return this.#inner.get(providerName, ownerDID);
     }
     async get(providerName, ownerDID) {
-        const credential = await this.#inner.get(providerName, ownerDID);
-        if (credential == null) return null;
+        const ref = await this.#inner.getCredentialRef(providerName, ownerDID);
+        if (ref == null) return null;
+        const { credential, entryID } = ref;
         if (this.#isExpiringSoon(credential) && credential.refreshToken != null) {
-            const refreshed = await this.#refresh(providerName, ownerDID, credential, credential.refreshToken);
+            const refreshed = await this.#refresh(providerName, ownerDID, entryID, credential, credential.refreshToken);
             return refreshed ?? credential;
         }
         return credential;
@@ -52,6 +53,12 @@ export class RefreshingCredentialProvider {
     delete(providerName, ownerDID) {
         return this.#inner.delete(providerName, ownerDID);
     }
+    // Passthrough: alias binding points an owner at an already-existing entry
+    // without minting or refreshing anything, so it needs none of this
+    // decorator's expiry/refresh logic.
+    bindAlias(providerName, ownerDID, entryID) {
+        return this.#inner.bindAlias(providerName, ownerDID, entryID);
+    }
     #isExpiringSoon(credential) {
         if (credential.expiresAt == null) return false;
         return credential.expiresAt.getTime() - Date.now() < this.#bufferMs;
@@ -67,14 +74,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, credential, refreshToken) {
-        const key = `${providerName}:${normalizeDID(ownerDID)}`;
+    async #refresh(providerName, ownerDID, entryID, 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 inFlight = this.#refreshInFlight.get(key);
         if (inFlight != null) {
             const outcome = await inFlight;
             return outcome.ok ? outcome.credential : null;
         }
-        const exchange = this.#exchange(providerName, ownerDID, credential, refreshToken);
+        const exchange = this.#exchange(providerName, ownerDID, entryID, credential, refreshToken);
         this.#refreshInFlight.set(key, exchange);
         let outcome;
         try {
@@ -102,7 +113,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, credential, refreshToken) {
+    async #exchange(providerName, ownerDID, entryID, credential, refreshToken) {
         const provider = this.#providers.find((p)=>p.name === providerName);
         if (provider == null) {
             return {
@@ -137,10 +148,12 @@ export class RefreshingCredentialProvider {
             accountLabel: credential.accountLabel,
             metadata: credential.metadata
         };
+        let write;
         try {
-            await this.#inner.set({
+            write = await this.#inner.setCredentialForEntry({
                 providerName,
                 ownerDID,
+                entryID,
                 credential: refreshed
             });
         } catch  {
@@ -155,6 +168,17 @@ export class RefreshingCredentialProvider {
                 category: rotated ? 'invalid_grant' : 'persistence'
             };
         }
+        // The entry read at the start of this refresh is gone (a delete+rebind
+        // landed mid-exchange) — checked BEFORE any rotation reasoning, because
+        // this is not a persistence failure or an invalidated refresh token: the
+        // user's own delete removed the target, and the refreshed credential must
+        // never overwrite whatever now sits at that provider+owner slot.
+        if (write === 'absent') {
+            return {
+                ok: false,
+                category: 'stale'
+            };
+        }
         return {
             ok: true,
             credential: refreshed

package/lib/validate.d.ts

@@ -0,0 +1,2 @@
+import type { Credential } from '@kubun/credential-types';
+export declare function assertValidCredentialShape(value: unknown): asserts value is Credential;

package/lib/validate.js

@@ -0,0 +1,30 @@
+import { CredentialInvalidEntry } from './errors.js';
+// Bind/refresh decrypt arbitrary stored bytes; deserializeCredential only JSON.parses
+// and casts, so `{}` or mistyped fields would pass. Validate against the typed
+// contract before trusting an entry as a credential.
+export function assertValidCredentialShape(value) {
+    if (value == null || typeof value !== 'object') {
+        throw new CredentialInvalidEntry('credential is not an object');
+    }
+    const c = value;
+    if (typeof c.accessToken !== 'string' || c.accessToken.length === 0) {
+        throw new CredentialInvalidEntry('accessToken must be a non-empty string');
+    }
+    if (!Array.isArray(c.scopes) || c.scopes.some((s)=>typeof s !== 'string')) {
+        throw new CredentialInvalidEntry('scopes must be an array of strings');
+    }
+    if (c.refreshToken != null && typeof c.refreshToken !== 'string') {
+        throw new CredentialInvalidEntry('refreshToken must be a string when present');
+    }
+    if (c.accountLabel != null && typeof c.accountLabel !== 'string') {
+        throw new CredentialInvalidEntry('accountLabel must be a string when present');
+    }
+    // expiresAt is serialized as an ISO string; an unparseable one deserializes to
+    // an Invalid Date, which silently disables the refresh comparison. Reject it here.
+    if (c.expiresAt != null && (typeof c.expiresAt !== 'string' || Number.isNaN(Date.parse(c.expiresAt)))) {
+        throw new CredentialInvalidEntry('expiresAt must be an ISO date string when present');
+    }
+    if (c.metadata != null && (typeof c.metadata !== 'object' || Array.isArray(c.metadata))) {
+        throw new CredentialInvalidEntry('metadata must be an object when present');
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/credential",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -18,12 +18,12 @@
     "@kokuin/jwe": "^0.1.0",
     "@kokuin/oauth": "^0.1.0",
     "@kokuin/token": "^0.5.0",
-    "@kubun/credential-types": "^0.17.0",
+    "@kubun/credential-types": "^0.17.1",
     "@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.0",
+    "@kubun/store-credential": "^0.17.4",
     "@noble/ciphers": "^2.4.0",
     "@noble/hashes": "^2.4.0",
     "@sozai/codec": "^0.4.0",
@@ -31,7 +31,11 @@
     "@sozai/runtime": "^0.1.0"
   },
   "devDependencies": {
-    "@kubun/db-better-sqlite": "^0.17.0"
+    "@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"
   },
   "publishConfig": {
     "access": "public"