@kubun/credential 0.17.3 → 0.18.0

package/lib/api.js

@@ -1,26 +1,222 @@
 import { normalizeDID } from '@kokuin/token';
-import { getCredentialStore } from '@kubun/store-credential';
+import { verifySignedRecord } from '@kubun/records';
+import { credentialRecordAdapter, getCredentialStore } from '@kubun/store-credential';
 import { fromUTF, toUTF } from '@sozai/codec';
-import { CredentialAliasAlreadyBound, CredentialBindNotAuthorized, CredentialEntryAlreadyAliased, CredentialInvalidEntry, CredentialNotFound, CredentialSupersededBranch } from './errors.js';
+import { CredentialAliasAlreadyBound, CredentialBindNotAuthorized, CredentialGrantAccountMismatch, CredentialGrantCopyUnavailable, CredentialGrantOwnerAmbiguous, CredentialGrantRehomeNotAuthorized, CredentialInvalidEntry, CredentialManagerStoreMismatch, CredentialNotFound, CredentialSupersededBranch } from './errors.js';
+import { credentialGrantEntryID } from './record-types.js';
 import { assertValidCredentialShape } from './validate.js';
 export function createCredentialAPI(params) {
     const getAliasStore = ()=>getCredentialStore(params.stores);
     const getCredentials = ()=>params.getCredentialManager(params.stores);
-    return {
+    const deviceDID = normalizeDID(params.serverWrappableDID);
+    const signedEntry = async (store, entryID, keyOwnerDID)=>{
+        const entry = await store.getEntry(entryID, keyOwnerDID);
+        const key = entry === undefined ? undefined : await store.getKey(entry.key_id, entry.owner_did);
+        if (key === undefined) return null;
+        const decision = await credentialRecordAdapter(store).get({
+            type: 'credential.entry',
+            owner: key.owner_did,
+            id: entryID
+        });
+        return decision?.copies[0] ?? null;
+    };
+    const grantKeyOwner = async ({ store, entryID, accountOwnerDID, providerName, grantDeviceDID = deviceDID, stores = params.stores, explicitSourceOwnerDID })=>{
+        const owner = normalizeDID(accountOwnerDID);
+        const alias = await store.getDeviceAliasEntry({
+            providerName,
+            ownerDID: owner,
+            deviceDID: grantDeviceDID
+        });
+        if (alias?.entryID === entryID) {
+            if (explicitSourceOwnerDID !== undefined && alias.entryOwnerDID !== normalizeDID(explicitSourceOwnerDID)) {
+                throw new CredentialGrantAccountMismatch(providerName, owner);
+            }
+            return alias.entryOwnerDID;
+        }
+        const controller = await params.resolveControllerOfOwner?.(owner, stores);
+        const candidates = controller == null ? [
+            owner
+        ] : [
+            normalizeDID(controller),
+            owner
+        ];
+        const heldOwners = await store.listEntryOwners(entryID);
+        if (explicitSourceOwnerDID !== undefined) {
+            const selected = normalizeDID(explicitSourceOwnerDID);
+            if (!candidates.includes(selected)) {
+                throw new CredentialGrantAccountMismatch(providerName, owner);
+            }
+            return selected;
+        }
+        if (heldOwners.length > 1) throw new CredentialGrantOwnerAmbiguous(entryID, heldOwners);
+        for (const candidate of new Set(candidates)){
+            if (heldOwners.includes(candidate)) return candidate;
+        }
+        return owner;
+    };
+    const aliasEntry = async (providerName, ownerDID)=>{
+        const store = await getAliasStore();
+        const entryID = await store.getDeviceAliasEntryID({
+            providerName,
+            ownerDID: normalizeDID(ownerDID),
+            deviceDID
+        });
+        if (entryID == null) return null;
+        const keyOwner = await grantKeyOwner({
+            store,
+            entryID,
+            accountOwnerDID: ownerDID,
+            providerName
+        });
+        const record = await signedEntry(store, entryID, keyOwner);
+        if (record == null) return null;
+        const op = await verifySignedRecord(record);
+        return op?.claim.meta.grantDeviceDID === deviceDID && op.claim.meta.grantName === providerName && op.claim.meta.grantOwnerDID === normalizeDID(ownerDID) ? entryID : null;
+    };
+    const localGrantRecord = async (entryID, providerName, ownerDID)=>{
+        const store = await getAliasStore();
+        const keyOwner = await grantKeyOwner({
+            store,
+            entryID,
+            accountOwnerDID: ownerDID,
+            providerName
+        });
+        const record = await signedEntry(store, entryID, keyOwner);
+        const op = record == null ? null : await verifySignedRecord(record);
+        return op != null && !op.claim.deleted && op.claim.meta.grantDeviceDID === deviceDID && op.claim.meta.grantName === providerName && op.claim.meta.grantOwnerDID === ownerDID;
+    };
+    const adoptionSource = async ({ stores, store, input })=>{
+        const owner = normalizeDID(input.ownerDID);
+        const from = normalizeDID(input.fromDeviceDID);
+        const aliasID = await store.getDeviceAliasEntryID({
+            providerName: input.providerName,
+            ownerDID: owner,
+            deviceDID: from
+        });
+        // The grant ID names the account, not the key owner. Backups need no local alias.
+        const sourceID = aliasID ?? credentialGrantEntryID(owner, from, input.providerName);
+        const sourceOwner = await grantKeyOwner({
+            store,
+            entryID: sourceID,
+            accountOwnerDID: owner,
+            providerName: input.providerName,
+            grantDeviceDID: from,
+            stores,
+            explicitSourceOwnerDID: input.sourceKeyOwnerDID
+        });
+        const source = await store.getEntry(sourceID, sourceOwner);
+        if (source == null) {
+            throw new CredentialGrantCopyUnavailable(input.providerName, owner, from);
+        }
+        const record = await signedEntry(store, sourceID, sourceOwner);
+        const op = record == null ? null : await verifySignedRecord(record);
+        if (op == null || op.claim.deleted || op.claim.meta.grantDeviceDID !== from || op.claim.meta.grantName !== input.providerName) {
+            throw new CredentialGrantCopyUnavailable(input.providerName, owner, from);
+        }
+        const key = await store.getKey(source.key_id, source.owner_did);
+        if (key == null || normalizeDID(op.claim.owner) !== normalizeDID(key.owner_did)) {
+            throw new CredentialGrantCopyUnavailable(input.providerName, owner, from);
+        }
+        const keyOwnerDID = normalizeDID(key.owner_did);
+        const controller = keyOwnerDID === owner ? null : await params.resolveControllerOfOwner?.(owner, stores);
+        if (op.claim.meta.grantOwnerDID !== owner || sourceID !== credentialGrantEntryID(owner, from, input.providerName) || keyOwnerDID !== owner && (controller == null || keyOwnerDID !== normalizeDID(controller))) {
+            throw new CredentialGrantAccountMismatch(input.providerName, owner);
+        }
+        return {
+            sourceID,
+            source,
+            keyOwnerDID
+        };
+    };
+    const api = {
+        getLocalDeviceDID: ()=>deviceDID,
+        async getGrantKeyOwnerDID (input) {
+            const store = await getAliasStore();
+            return (await adoptionSource({
+                stores: params.stores,
+                store,
+                input
+            })).keyOwnerDID;
+        },
+        async adoptCredentialGrant (input, authorizedKeyOwnerDID) {
+            const owner = normalizeDID(input.ownerDID);
+            const from = normalizeDID(input.fromDeviceDID);
+            const to = normalizeDID(input.toDeviceDID);
+            if (to !== deviceDID || from === to) {
+                throw new CredentialBindNotAuthorized(input.providerName, input.ownerDID);
+            }
+            if (input.sourceKeyOwnerDID !== undefined && authorizedKeyOwnerDID === undefined) {
+                throw new CredentialBindNotAuthorized(input.providerName, input.ownerDID);
+            }
+            await (await params.getCredentialManager(params.stores)).ensureRemovalRecovery();
+            return params.stores.withTransaction(async (tx)=>{
+                const store = await getCredentialStore(tx);
+                const credentials = await params.getCredentialManager(tx, true);
+                const { sourceID, source, keyOwnerDID } = await adoptionSource({
+                    stores: tx,
+                    store,
+                    input
+                });
+                if (authorizedKeyOwnerDID != null && keyOwnerDID !== normalizeDID(authorizedKeyOwnerDID)) {
+                    throw new CredentialBindNotAuthorized(input.providerName, input.ownerDID);
+                }
+                const plaintext = await credentials.readEntry({
+                    entryID: sourceID,
+                    ownerDID: keyOwnerDID
+                });
+                const targetID = await credentials.putEntry(source.key_id, plaintext, {
+                    grantDeviceDID: to,
+                    grantName: input.providerName,
+                    grantOwnerDID: owner
+                });
+                await store.setDeviceAliasEntryID({
+                    providerName: input.providerName,
+                    ownerDID: owner,
+                    deviceDID: to,
+                    entryID: targetID,
+                    entryOwnerDID: keyOwnerDID
+                });
+                await credentials.deleteEntry({
+                    entryID: sourceID,
+                    ownerDID: keyOwnerDID
+                });
+                await store.deleteDeviceAliasIfEntry({
+                    providerName: input.providerName,
+                    ownerDID: owner,
+                    deviceDID: from,
+                    entryID: sourceID
+                });
+                return {
+                    adopted: true
+                };
+            });
+        },
         async listSubjects (providerName) {
-            return (await getAliasStore()).listAliasKeys(providerName);
+            return (await getAliasStore()).listDeviceAliasOwnersForProvider({
+                providerName,
+                deviceDID
+            });
         },
         async getCredential (providerName, ownerDID) {
             const store = await getAliasStore();
-            const entryID = await store.getAliasEntryID(providerName, normalizeDID(ownerDID));
+            const entryID = await aliasEntry(providerName, 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;
+            const keyOwner = await grantKeyOwner({
+                store,
+                entryID,
+                accountOwnerDID: ownerDID,
+                providerName
+            });
+            if (await store.getEntry(entryID, keyOwner) == null) return null;
             try {
                 const credentials = await getCredentials();
-                return toUTF(await credentials.readEntry(entryID));
+                return toUTF(await credentials.readEntry({
+                    entryID,
+                    ownerDID: keyOwner
+                }));
             } catch (error) {
                 if (error instanceof CredentialSupersededBranch) {
                     params.logger.warn('Credential entry {entryID} for provider {providerName} belongs to a superseded branch', {
@@ -36,14 +232,21 @@ export function createCredentialAPI(params) {
             // Reflects the current pointer, not the winning branch — no superseded-branch guard
             // (it never decrypts). Callers must gate on getCredential() != null so a loser-branch
             // pointer's provenance is never surfaced.
-            const store = await getAliasStore();
-            const entryID = await store.getAliasEntryID(providerName, normalizeDID(ownerDID));
+            const entryID = await aliasEntry(providerName, ownerDID);
             if (entryID == null) return null;
-            return (await getCredentials()).getEntryProvenance(entryID);
+            const store = await getAliasStore();
+            return (await getCredentials()).getEntryProvenance({
+                entryID,
+                ownerDID: await grantKeyOwner({
+                    store,
+                    entryID,
+                    accountOwnerDID: ownerDID,
+                    providerName
+                })
+            });
         },
         async setCredential (providerName, ownerDID, credential) {
-            const store = await getAliasStore();
-            const entryID = await store.getAliasEntryID(providerName, normalizeDID(ownerDID));
+            const entryID = await aliasEntry(providerName, ownerDID);
             if (entryID == null) {
                 throw new Error(`No connector credential to update for provider "${providerName}"; create it through the authorization flow`);
             }
@@ -51,117 +254,211 @@ export function createCredentialAPI(params) {
             // under it. No key is minted and no wrapping is touched, so a refresh
             // cannot change who can read the credential.
             const credentials = await getCredentials();
-            await credentials.updateEntry(entryID, fromUTF(credential));
+            const store = await getAliasStore();
+            await credentials.updateEntry({
+                entryID,
+                ownerDID: await grantKeyOwner({
+                    store,
+                    entryID,
+                    accountOwnerDID: ownerDID,
+                    providerName
+                })
+            }, fromUTF(credential));
         },
         async createCredential (input) {
-            const { providerName, ownerDID, ownerWrappableDID, credential } = input;
-            const store = await getAliasStore();
-            const credentials = await getCredentials();
-            // Wrapping to a DID needs only that DID's published key, so an engine that
-            // cannot decrypt would mint this key perfectly and then be unable to read
-            // it — a failure that surfaces at the first headless sync, far from here.
-            // This is where `cipher == null` used to fail closed, and it still does.
-            if (!credentials.availableFactors().includes('did')) {
-                throw new Error(`Cannot create a connector credential for "${providerName}": this engine's identity cannot decrypt, so it could never read back what it stored`);
-            }
-            // Two wrappings from the first write, not one plus a later grant: the
-            // server has to read this to run sync, and the owner has to be able to
-            // rotate and revoke it. Owner is authority, a different question from who
-            // can decrypt: when a controller is supplied it is the owner, so a device
-            // revoke goes through the controller's capability chain rather than the
-            // device self-authorizing; absent one the device owns its own key.
-            //
-            // The two spellings below are deliberately different questions about the
-            // same identity, and NOT interchangeable: `owner_did` is an equality key
-            // and so is normalized, while a recipient is encrypted to and must keep
-            // its wrappable form. `ownerWrappableDID` is therefore NOT normalized.
-            // Normalizing a `did:peer:4` recipient hands the short form to
-            // `deriveSharedSecret`, which resolves no document and no agreement key —
-            // do not fold these together.
-            const wrappings = [
-                [
-                    {
-                        kind: 'did',
-                        recipientDID: ownerWrappableDID
+            // A controller-log pull may consult remote providers, so resolve before the grant lock.
+            if (!params.wrappingRecipientsPrewarmed) {
+                const methods = params.getControllerMethods(params.stores);
+                const recipients = new Set([
+                    input.ownerWrappableDID,
+                    params.serverWrappableDID,
+                    input.controllerWrappableDID
+                ]);
+                for (const recipient of recipients){
+                    if (recipient == null) continue;
+                    for (const method of methods){
+                        if (recipient.startsWith(`did:${method.method}:`)) {
+                            await method.resolve(recipient, {});
+                        }
                     }
-                ],
-                [
-                    {
-                        kind: 'did',
-                        recipientDID: params.serverWrappableDID
+                }
+            }
+            await params.stores.withTransaction(async (tx)=>{
+                const { providerName, ownerDID, ownerWrappableDID, credential } = input;
+                const store = await getCredentialStore(tx);
+                const credentials = await params.getCredentialManager(tx);
+                if (credentials.store !== store) throw new CredentialManagerStoreMismatch();
+                // Wrapping to a DID needs only that DID's published key, so an engine that
+                // cannot decrypt would mint this key perfectly and then be unable to read
+                // it — a failure that surfaces at the first headless sync, far from here.
+                // This is where `cipher == null` used to fail closed, and it still does.
+                if (!credentials.availableFactors().includes('did')) {
+                    throw new Error(`Cannot create a connector credential for "${providerName}": this engine's identity cannot decrypt, so it could never read back what it stored`);
+                }
+                // Two wrappings from the first write, not one plus a later grant: the
+                // server has to read this to run sync, and the owner has to be able to
+                // rotate and revoke it. Owner is authority, a different question from who
+                // can decrypt: when a controller is supplied it is the owner, so a device
+                // revoke goes through the controller's capability chain rather than the
+                // device self-authorizing; absent one the device owns its own key.
+                //
+                // The two spellings below are deliberately different questions about the
+                // same identity, and NOT interchangeable: `owner_did` is an equality key
+                // and so is normalized, while a recipient is encrypted to and must keep
+                // its wrappable form. `ownerWrappableDID` is therefore NOT normalized.
+                // Normalizing a `did:peer:4` recipient hands the short form to
+                // `deriveSharedSecret`, which resolves no document and no agreement key —
+                // do not fold these together.
+                const wrappings = [
+                    [
+                        {
+                            kind: 'did',
+                            recipientDID: ownerWrappableDID
+                        }
+                    ],
+                    [
+                        {
+                            kind: 'did',
+                            recipientDID: params.serverWrappableDID
+                        }
+                    ]
+                ];
+                // A recovery recipient (e.g. a controller / seed-holder), so the credential
+                // survives device loss. Opt-in: absent when the caller supplied none. Kept
+                // in its wrappable form for the same reason as the two above — it is
+                // encrypted to, not compared against.
+                if (input.controllerWrappableDID != null) {
+                    wrappings.push([
+                        {
+                            kind: 'did',
+                            recipientDID: input.controllerWrappableDID
+                        }
+                    ]);
+                }
+                // The controller owns the key when supplied (its canonical DID equals the
+                // normalized wrappable form); the account pointer below stays keyed on the
+                // device — ownership and account scoping are separate concerns.
+                const keyOwnerDID = input.controllerWrappableDID != null ? normalizeDID(input.controllerWrappableDID) : normalizeDID(ownerDID);
+                const grantOwnerDID = normalizeDID(ownerDID);
+                const entryID = credentialGrantEntryID(grantOwnerDID, deviceDID, providerName);
+                await store.lockKeyRow(`grant-entry:${entryID}`);
+                const priorOwners = [];
+                for (const priorOwner of (await store.listEntryOwners(entryID))){
+                    const record = await signedEntry(store, entryID, priorOwner);
+                    const op = record == null ? null : await verifySignedRecord(record);
+                    if (op != null && !op.claim.deleted && op.claim.meta.grantDeviceDID === deviceDID && op.claim.meta.grantName === providerName && op.claim.meta.grantOwnerDID === grantOwnerDID) {
+                        priorOwners.push(priorOwner);
                     }
-                ]
-            ];
-            // A recovery recipient (e.g. a controller / seed-holder), so the credential
-            // survives device loss. Opt-in: absent when the caller supplied none. Kept
-            // in its wrappable form for the same reason as the two above — it is
-            // encrypted to, not compared against.
-            if (input.controllerWrappableDID != null) {
-                wrappings.push([
-                    {
-                        kind: 'did',
-                        recipientDID: input.controllerWrappableDID
+                }
+                if (priorOwners.length > 0) {
+                    for (const owner of new Set([
+                        ...priorOwners,
+                        keyOwnerDID
+                    ])){
+                        const authorized = input.authorizeKeyOwnerDID ? await input.authorizeKeyOwnerDID(owner) : await params.authorizeKeyOwnerDID?.(owner, tx);
+                        if (authorized !== true) throw new CredentialGrantRehomeNotAuthorized(entryID);
                     }
-                ]);
-            }
-            // The controller owns the key when supplied (its canonical DID equals the
-            // normalized wrappable form); the account pointer below stays keyed on the
-            // device — ownership and account scoping are separate concerns.
-            const keyOwnerDID = input.controllerWrappableDID != null ? normalizeDID(input.controllerWrappableDID) : normalizeDID(ownerDID);
-            const keyID = await credentials.createKey({
-                ownerDID: keyOwnerDID,
-                wrappings,
-                methods: params.getControllerMethods(params.stores)
+                }
+                for (const priorOwner of priorOwners){
+                    await credentials.deleteEntry({
+                        entryID,
+                        ownerDID: priorOwner
+                    });
+                }
+                const keyID = await credentials.createKey({
+                    ownerDID: keyOwnerDID,
+                    wrappings,
+                    methods: params.getControllerMethods(tx, {
+                        localOnly: true
+                    })
+                });
+                const writtenEntryID = await credentials.putEntry(keyID, fromUTF(credential), {
+                    grantDeviceDID: deviceDID,
+                    grantName: providerName,
+                    grantOwnerDID
+                });
+                await store.setDeviceAliasEntryID({
+                    providerName,
+                    ownerDID: normalizeDID(ownerDID),
+                    deviceDID,
+                    entryID: writtenEntryID,
+                    entryOwnerDID: keyOwnerDID
+                });
             });
-            const entryID = await credentials.putEntry(keyID, fromUTF(credential));
-            await store.setAliasEntryID(providerName, normalizeDID(ownerDID), entryID);
         },
         async deleteCredential (providerName, ownerDID) {
             const store = await getAliasStore();
             const owner = normalizeDID(ownerDID);
-            const entryID = await store.getAliasEntryID(providerName, owner);
-            // 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.
+            const entryID = await aliasEntry(providerName, owner);
+            // Delete the entry before clearing its local pointer; readers treat the
+            // briefly dangling pointer as absent.
             // 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);
+            await credentials.deleteEntry({
+                entryID,
+                ownerDID: await grantKeyOwner({
+                    store,
+                    entryID,
+                    accountOwnerDID: owner,
+                    providerName
+                })
+            });
             // 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);
+            await store.deleteDeviceAliasIfEntry({
+                providerName,
+                ownerDID: owner,
+                deviceDID,
+                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 (entryID !== credentialGrantEntryID(owner, deviceDID, providerName)) {
+                if (entryID.startsWith('grant:')) {
+                    throw new CredentialBindNotAuthorized(providerName, ownerDID);
+                }
+                throw new CredentialNotFound('Credential entry', entryID);
+            }
+            // Gate B: the entry's key must belong to this account. The signed grant
+            // binds the account independently.
+            const store = await getAliasStore();
+            const expectedKeyOwner = await grantKeyOwner({
+                store,
+                entryID,
+                accountOwnerDID: owner,
+                providerName
+            });
+            const keyOwner = await credentials.getEntryKeyOwnerDID({
+                entryID,
+                ownerDID: expectedKeyOwner
+            });
             if (keyOwner == null) {
                 throw new CredentialNotFound('Credential entry', entryID);
             }
             if (normalizeDID(keyOwner) !== owner) {
                 throw new CredentialBindNotAuthorized(providerName, ownerDID);
             }
-            const store = await getAliasStore();
+            if (!await localGrantRecord(entryID, providerName, owner)) {
+                throw new CredentialBindNotAuthorized(providerName, ownerDID);
+            }
             // 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) {
+            if (await aliasEntry(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);
+            const bytes = await credentials.readEntry({
+                entryID,
+                ownerDID: keyOwner
+            });
             let parsed;
             try {
                 parsed = JSON.parse(toUTF(bytes));
@@ -171,39 +468,59 @@ export function createCredentialAPI(params) {
                 });
             }
             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
+            const existing = await aliasEntry(providerName, owner);
+            if (existing != null && existing !== entryID) {
                 throw new CredentialAliasAlreadyBound(providerName, ownerDID);
             }
-            throw new CredentialEntryAlreadyAliased(providerName, entryID) // conflict: 'entry'
-            ;
+            await store.setDeviceAliasEntryID({
+                providerName,
+                ownerDID: owner,
+                deviceDID,
+                entryID,
+                entryOwnerDID: keyOwner
+            });
         },
         getControllerMethods () {
             return params.getControllerMethods(params.stores);
         },
         async getCredentialRef (providerName, ownerDID) {
+            // Projected without the version: this shape is also a service wire result.
+            const ref = await api.getVersionedCredentialRef(providerName, ownerDID);
+            return ref == null ? null : {
+                credential: ref.credential,
+                entryID: ref.entryID
+            };
+        },
+        async getVersionedCredentialRef (providerName, ownerDID) {
             const store = await getAliasStore();
-            const entryID = await store.getAliasEntryID(providerName, normalizeDID(ownerDID));
+            const entryID = await aliasEntry(providerName, 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
-                };
+                const keyOwner = await grantKeyOwner({
+                    store,
+                    entryID,
+                    accountOwnerDID: ownerDID,
+                    providerName
+                });
+                for(let attempt = 0; attempt < 5; attempt += 1){
+                    const before = await store.getEntry(entryID, keyOwner);
+                    if (before == null) return null;
+                    const bytes = await credentials.readEntry({
+                        entryID,
+                        ownerDID: keyOwner
+                    });
+                    const after = await store.getEntry(entryID, keyOwner);
+                    if (after == null) return null;
+                    if (before.hlc === after.hlc) {
+                        return {
+                            credential: toUTF(bytes),
+                            entryID,
+                            version: before.hlc
+                        };
+                    }
+                }
+                throw new CredentialInvalidEntry('credential entry changed during versioned read');
             } catch (error) {
                 if (error instanceof CredentialSupersededBranch) {
                     params.logger.warn('Credential entry {entryID} for provider {providerName} belongs to a superseded branch', {
@@ -216,8 +533,35 @@ export function createCredentialAPI(params) {
             }
         },
         async setCredentialForEntry (params) {
+            if (await aliasEntry(params.providerName, params.ownerDID) !== params.entryID) return 'absent';
             const credentials = await getCredentials();
-            return await credentials.updateEntryIfPresent(params.entryID, fromUTF(params.credential));
+            const store = await getAliasStore();
+            return await credentials.updateEntryIfPresent({
+                entryID: params.entryID,
+                ownerDID: await grantKeyOwner({
+                    store,
+                    entryID: params.entryID,
+                    accountOwnerDID: params.ownerDID,
+                    providerName: params.providerName
+                })
+            }, fromUTF(params.credential));
+        },
+        async setCredentialForEntryIfUnchanged (params) {
+            if (await aliasEntry(params.providerName, params.ownerDID) !== params.entryID) return 'absent';
+            const credentials = await getCredentials();
+            const store = await getAliasStore();
+            return await credentials.updateEntryIfUnchanged({
+                entryID: params.entryID,
+                plaintext: fromUTF(params.credential),
+                expectedHLC: params.expectedVersion,
+                ownerDID: await grantKeyOwner({
+                    store,
+                    entryID: params.entryID,
+                    accountOwnerDID: params.ownerDID,
+                    providerName: params.providerName
+                })
+            });
         }
     };
+    return api;
 }