@kubun/plugin-credential 0.17.4 → 0.18.0

package/lib/context.d.ts

@@ -58,12 +58,12 @@ export type PutCredentialEntryInput = {
 };
 export type CredentialQueryContext = {
     getKey(keyID: string): Promise<CredentialKeyResult>;
-    getEntry(entryID: string): Promise<CredentialEntryResult>;
+    getEntry(entryID: string, ownerDID: string): Promise<CredentialEntryResult>;
     listEntries(keyID: string): Promise<Array<string>>;
     putKey(input: PutCredentialKeyInput): Promise<CredentialKeyResult>;
     putEntry(input: PutCredentialEntryInput): Promise<CredentialEntryResult>;
     deleteKey(keyID: string): Promise<boolean>;
-    deleteEntry(entryID: string): Promise<boolean>;
+    deleteEntry(entryID: string, ownerDID: string): Promise<boolean>;
 };
 export declare function createCredentialQueryContext(params: {
     getStore: () => Promise<CredentialStoreAPI>;

package/lib/context.js

@@ -1,3 +1,4 @@
+import { normalizeDID } from '@kokuin/token';
 import { entryProvenanceFields } from '@kubun/credential';
 import { HLC } from '@kubun/hlc';
 import { CredentialEntryID, CredentialKeyID } from '@kubun/id';
@@ -69,7 +70,7 @@ export function createCredentialQueryContext(params) {
         return await requireAuthorized(store, await store.getKey(keyID), keyID, authorization);
     }
     async function keyResult(store, key) {
-        const wrappings = await store.listWrappings(key.key_id);
+        const wrappings = await store.listWrappings(key.key_id, undefined, key.owner_did);
         return {
             keyID: key.key_id,
             ownerDID: key.owner_did,
@@ -86,15 +87,15 @@ export function createCredentialQueryContext(params) {
             const store = await getStore();
             return await keyResult(store, await loadKey(store, keyID, 'read'));
         },
-        async getEntry (entryID) {
+        async getEntry (entryID, ownerDID) {
             const store = await getStore();
-            const entry = await store.getEntryWithProvenance(entryID);
+            const entry = await store.getEntryWithProvenance(entryID, normalizeDID(ownerDID));
             if (entry == null) {
                 throw notFound('Credential entry', entryID);
             }
             // An entry carries no authorization of its own. Its key does, and that is
             // the only thing that decides who may read the ciphertext.
-            await loadKey(store, entry.key_id, 'read');
+            await requireAuthorized(store, await store.getKey(entry.key_id, entry.owner_did), entry.key_id, 'read');
             return toEntryResult(entry);
         },
         async listEntries (keyID) {
@@ -133,7 +134,7 @@ export function createCredentialQueryContext(params) {
                 suite: input.suite,
                 version: input.version,
                 state: 'active'
-            }, null);
+            });
             for (const wrapping of input.wrappings){
                 await store.putWrapping({
                     wrappingID: wrapping.wrappingID,
@@ -143,7 +144,7 @@ export function createCredentialQueryContext(params) {
                     iv: fromB64(wrapping.iv),
                     wrappedKey: fromB64(wrapping.wrappedKey),
                     recipientDID: wrapping.recipientDID ?? null
-                }, null);
+                });
             }
             return await keyResult(store, await loadKey(store, input.keyID, 'administer'));
         },
@@ -156,7 +157,7 @@ export function createCredentialQueryContext(params) {
             const store = await getStore();
             // Administrative, not read: a recipient can decrypt this key's entries,
             // which is not a reason to let it write into someone else's vault.
-            await loadKey(store, input.keyID, 'administer');
+            const key = await loadKey(store, input.keyID, 'administer');
             await store.putEntry({
                 entryID: input.entryID,
                 keyID: input.keyID,
@@ -164,8 +165,8 @@ export function createCredentialQueryContext(params) {
                 iv: fromB64(input.iv),
                 ciphertext: fromB64(input.ciphertext),
                 hlc: HLC.serialize(params.hlc.now())
-            }, null);
-            const written = await store.getEntryWithProvenance(input.entryID);
+            });
+            const written = await store.getEntryWithProvenance(input.entryID, key.owner_did);
             if (written == null) {
                 throw notFound('Credential entry', input.entryID);
             }
@@ -174,17 +175,17 @@ export function createCredentialQueryContext(params) {
         async deleteKey (keyID) {
             const store = await getStore();
             await loadKey(store, keyID, 'administer');
-            await store.deleteKey(keyID, null);
+            await store.deleteKey(keyID);
             return true;
         },
-        async deleteEntry (entryID) {
+        async deleteEntry (entryID, ownerDID) {
             const store = await getStore();
-            const entry = await store.getEntry(entryID);
+            const entry = await store.getEntry(entryID, normalizeDID(ownerDID));
             if (entry == null) {
                 throw notFound('Credential entry', entryID);
             }
             await loadKey(store, entry.key_id, 'administer');
-            await store.deleteEntry(entryID, null);
+            await store.deleteEntry(entryID, entry.owner_did);
             return true;
         }
     };

package/lib/schema.js

@@ -61,7 +61,7 @@ input CredentialEntryInput {
 
 extend type Query {
   credentialKey(keyID: String!): CredentialKey!
-  credentialEntry(entryID: String!): CredentialEntry!
+  credentialEntry(entryID: String!, ownerDID: String!): CredentialEntry!
   credentialEntries(keyID: String!): [String!]!
 }
 
@@ -69,7 +69,7 @@ extend type Mutation {
   putCredentialKey(input: CredentialKeyInput!): CredentialKey!
   putCredentialEntry(input: CredentialEntryInput!): CredentialEntry!
   deleteCredentialKey(keyID: String!): Boolean!
-  deleteCredentialEntry(entryID: String!): Boolean!
+  deleteCredentialEntry(entryID: String!, ownerDID: String!): Boolean!
 }
 `;
 function requireCredential(ctx) {
@@ -97,14 +97,14 @@ function requireCredential(ctx) {
         resolvers: {
             queryFields: {
                 credentialKey: (_source, args, context)=>requireCredential(context).getKey(args.keyID),
-                credentialEntry: (_source, args, context)=>requireCredential(context).getEntry(args.entryID),
+                credentialEntry: (_source, args, context)=>requireCredential(context).getEntry(args.entryID, args.ownerDID),
                 credentialEntries: (_source, args, context)=>requireCredential(context).listEntries(args.keyID)
             },
             mutationFields: {
                 putCredentialKey: (_source, args, context)=>requireCredential(context).putKey(args.input),
                 putCredentialEntry: (_source, args, context)=>requireCredential(context).putEntry(args.input),
                 deleteCredentialKey: (_source, args, context)=>requireCredential(context).deleteKey(args.keyID),
-                deleteCredentialEntry: (_source, args, context)=>requireCredential(context).deleteEntry(args.entryID)
+                deleteCredentialEntry: (_source, args, context)=>requireCredential(context).deleteEntry(args.entryID, args.ownerDID)
             }
         }
     };

package/lib/service.d.ts

@@ -1,4 +1,10 @@
+import type { CreateCredentialManagerParams } from '@kubun/credential';
 import type { KubunPlugin, PluginFactoryParams } from '@kubun/engine';
+/** Bind the service's recovery preflight and current removal set to each manager. */
+export declare function createServiceCredentialManager(params: Pick<CreateCredentialManagerParams, 'store' | 'identity' | 'runtime' | 'hlc' | 'authority'> & {
+    ensure(): Promise<void>;
+    removedDevices(ownerDID: string): Promise<ReadonlySet<string>>;
+}): import("@kubun/credential").CredentialManager;
 /**
  * The credential service provider. Unlike {@link createCredentialPlugin}
  * (graph-schema-only, for an engine that consumes credentials), this registers a

package/lib/service.js

@@ -1,6 +1,8 @@
 import { isSigningIdentity, normalizeDID } from '@kokuin/token';
-import { CredentialAliasAlreadyBound, CredentialBindNotAuthorized, CredentialEntryAlreadyAliased, CredentialInvalidEntry, CredentialKeyVersionMismatch, CredentialNotFound, CredentialSupersededBranch, createCredentialAPI, createCredentialManager, wrappableDID } from '@kubun/credential';
+import { CredentialAliasAlreadyBound, CredentialBindNotAuthorized, CredentialEntryAlreadyAliased, CredentialGrantCopyUnavailable, CredentialGrantOwnerAmbiguous, CredentialGrantRehomeNotAuthorized, CredentialInvalidEntry, CredentialKeyVersionMismatch, CredentialNotFound, CredentialSupersededBranch, createCredentialAPI, createCredentialManager, wrappableDID } from '@kubun/credential';
+import { controllerHeadVersion, resolveCurrentControllerOfDevice } from '@kubun/engine';
 import { authorizeRead, authorizeWrite, ServiceAuthorizationError } from '@kubun/plugin-service-server';
+import { credentialServiceProtocol } from '@kubun/service-credential-api';
 import { credentialStoreDefinition, getCredentialStore } from '@kubun/store-credential';
 // The service boundary has no CREDENTIAL_* → KB* mapping; toHandlerError forwards
 // a thrown error's `code` only when it is already a registered KubunErrorCode,
@@ -22,6 +24,18 @@ function translateCredentialError(err) {
     if (err instanceof CredentialNotFound) {
         return withCode(err, 'KB02', 'CREDENTIAL_NOT_FOUND');
     }
+    if (err instanceof CredentialGrantCopyUnavailable) {
+        return withCode(err, 'KB02', 'CREDENTIAL_GRANT_COPY_UNAVAILABLE');
+    }
+    if (err instanceof CredentialGrantOwnerAmbiguous) {
+        return withCode(err, 'KB04', 'CREDENTIAL_GRANT_OWNER_AMBIGUOUS');
+    }
+    if (err instanceof CredentialGrantRehomeNotAuthorized) {
+        return withCode(err, 'KB07', 'CREDENTIAL_GRANT_REHOME_NOT_AUTHORIZED');
+    }
+    if (err instanceof Error && 'code' in err && err.code === 'CREDENTIAL_GRANT_ACCOUNT_MISMATCH') {
+        return withCode(err, 'KB07', 'CREDENTIAL_GRANT_ACCOUNT_MISMATCH');
+    }
     if (err instanceof CredentialInvalidEntry) {
         return withCode(err, 'KB01', 'CREDENTIAL_INVALID_ENTRY');
     }
@@ -66,6 +80,19 @@ function readAccountPeek(raw) {
         providerAccount
     };
 }
+/** Bind the service's recovery preflight and current removal set to each manager. */ export function createServiceCredentialManager(params) {
+    return createCredentialManager({
+        store: params.store,
+        identity: params.identity,
+        runtime: params.runtime,
+        hlc: params.hlc,
+        authority: params.authority,
+        removalRecovery: {
+            ensure: params.ensure,
+            removedDevices: params.removedDevices
+        }
+    });
+}
 /**
  * The credential service provider. Unlike {@link createCredentialPlugin}
  * (graph-schema-only, for an engine that consumes credentials), this registers a
@@ -90,12 +117,45 @@ function readAccountPeek(raw) {
         }
         const identity = params.identity;
         const logger = params.getLogger('credential-service');
-        const getCredentialManager = async (stores)=>createCredentialManager({
+        const recoveryResolver = params.controllerResolverFor(params.db);
+        const resolveRecoveryController = (did)=>resolveCurrentControllerOfDevice(params.db, did, recoveryResolver);
+        const recoveryOptions = {
+            resolveController: resolveRecoveryController,
+            removedDevices: async (ownerDID)=>await recoveryResolver.resolveDenySet?.(ownerDID) ?? new Set(),
+            methods: [
+                recoveryResolver
+            ],
+            headVersion: async (ownerDID)=>controllerHeadVersion(await params.controllerHead(params.db, ownerDID))
+        };
+        const getCredentialManager = async (stores, recoveryChecked = false)=>createServiceCredentialManager({
                 store: await getCredentialStore(stores),
                 identity,
                 runtime: params.runtime,
-                hlc: params.hlc
+                hlc: params.hlc,
+                ensure: recoveryChecked ? async ()=>{} : checkRemovalRecovery,
+                removedDevices: recoveryOptions.removedDevices
             });
+        const recoveryManager = getCredentialStore(params.db).then((store)=>createCredentialManager({
+                store,
+                identity,
+                runtime: params.runtime,
+                hlc: params.hlc,
+                removalRecovery: recoveryOptions,
+                authority: {
+                    ownerForNewKey: async ()=>await resolveRecoveryController(identity.id) ?? identity.id,
+                    authorize: async (_action, { key })=>normalizeDID(key.owner_did) === await resolveRecoveryController(identity.id),
+                    authorizeRevocation: async ({ key })=>normalizeDID(key.owner_did) === await resolveRecoveryController(identity.id)
+                }
+            }));
+        let completedRecoveryHead;
+        const checkRemovalRecovery = async ()=>{
+            const owner = await resolveRecoveryController(identity.id);
+            if (owner === null) return;
+            const version = await recoveryOptions.headVersion(owner);
+            if (version === completedRecoveryHead) return;
+            await (await recoveryManager).recoverRemovedDevices(recoveryOptions);
+            completedRecoveryHead = version;
+        };
         // The mint folds inside its own write tx (`writeInTx`), so its resolver is
         // local-only: a recipient miss must fail closed, never pull a controller log
         // through `consultProviders` while the write lock is held. The pre-warm below
@@ -108,19 +168,42 @@ function readAccountPeek(raw) {
         // The seam is bound to whatever provider it is built over: reads run against
         // the root, writes against a transaction (below). A manager, alias store and
         // controller resolver all read from that same provider.
-        const makeSeam = (stores)=>createCredentialAPI({
+        const makeSeam = (stores, recoveryChecked = false)=>createCredentialAPI({
                 stores,
                 logger,
-                getCredentialManager,
+                getCredentialManager: (provider, checked)=>getCredentialManager(provider, recoveryChecked || checked === true),
                 serverWrappableDID: wrappableDID(params.identity),
-                getControllerMethods
+                getControllerMethods,
+                wrappingRecipientsPrewarmed: true,
+                resolveControllerOfOwner: (ownerDID, provider)=>resolveCurrentControllerOfDevice(provider, ownerDID, params.controllerResolverFor(provider, {
+                        localOnly: true
+                    }))
             });
         const readSeam = makeSeam(params.db);
+        const localDeviceDID = normalizeDID(identity.id);
+        const requireLocalGrantAddress = (param)=>{
+            if (param.deviceDID === undefined) return;
+            try {
+                if (normalizeDID(param.deviceDID) === localDeviceDID) return;
+            } catch  {
+            // Invalid device addresses are refused by the same named credential error.
+            }
+            throw translateCredentialError(new CredentialBindNotAuthorized(param.providerName, param.ownerDID));
+        };
+        const localRead = async (context, empty, proceed)=>context.iss != null && normalizeDID(context.iss) === localDeviceDID || await context.authorize(localDeviceDID) ? proceed() : empty;
+        const localWrite = async (context)=>{
+            if ((context.iss == null || normalizeDID(context.iss) !== localDeviceDID) && !await context.authorize(localDeviceDID)) {
+                throw new ServiceAuthorizationError('The caller cannot spend this device grant');
+            }
+        };
         // A mint/refresh/delete is multi-statement (key + wrappings + entry + alias
         // pointer). Outside a graph mutation there is no ambient transaction, so run
         // each write in its own: a mid-mint failure would otherwise leave an
         // orphan key with no alias pointer in the vault.
-        const writeInTx = (fn)=>params.db.withTransaction((tx)=>fn(makeSeam(tx)));
+        const writeInTx = async (fn)=>{
+            await checkRemovalRecovery();
+            return await params.db.withTransaction((tx)=>fn(makeSeam(tx, true)));
+        };
         // A first-time `did:kokuin:` owner (or recovery controller) may hold no log in
         // this engine's controller store yet. Resolve it through the pull-allowed ROOT
         // resolver before the mint tx opens: on a store miss this pulls via the
@@ -148,7 +231,19 @@ function readAccountPeek(raw) {
                     context,
                     subject: param.ownerDID,
                     emptyResult: null,
-                    proceed: ()=>readSeam.getCredential(param.providerName, param.ownerDID)
+                    proceed: ()=>localRead(context, null, ()=>readSeam.getCredential(param.providerName, param.ownerDID))
+                });
+            },
+            'credential/get-ref': (context)=>{
+                const param = context.param;
+                return authorizeRead({
+                    context,
+                    subject: param.ownerDID,
+                    emptyResult: null,
+                    proceed: ()=>localRead(context, null, ()=>{
+                            requireLocalGrantAddress(param);
+                            return readSeam.getVersionedCredentialRef(param.providerName, param.ownerDID);
+                        })
                 });
             },
             // The same vault read as `credential/get` — the DB credential API, which
@@ -160,11 +255,11 @@ function readAccountPeek(raw) {
                     context,
                     subject: param.ownerDID,
                     emptyResult: null,
-                    proceed: async ()=>{
-                        const raw = await readSeam.getCredential(param.providerName, param.ownerDID);
-                        if (raw == null) return null;
-                        return readAccountPeek(raw);
-                    }
+                    proceed: ()=>localRead(context, null, async ()=>{
+                            const raw = await readSeam.getCredential(param.providerName, param.ownerDID);
+                            if (raw == null) return null;
+                            return readAccountPeek(raw);
+                        })
                 });
             },
             'credential/provenance': (context)=>{
@@ -173,7 +268,7 @@ function readAccountPeek(raw) {
                     context,
                     subject: param.ownerDID,
                     emptyResult: null,
-                    proceed: ()=>readSeam.getCredentialProvenance(param.providerName, param.ownerDID)
+                    proceed: ()=>localRead(context, null, ()=>readSeam.getCredentialProvenance(param.providerName, param.ownerDID))
                 });
             },
             'credential/create': async (context)=>{
@@ -182,6 +277,7 @@ function readAccountPeek(raw) {
                     context,
                     subject: param.ownerDID
                 });
+                await localWrite(context);
                 // `ownerWrappableDID` is the wrappable spelling of the SAME identity the
                 // authorizer just cleared (`ownerDID`). Nothing downstream re-checks that,
                 // so without this a caller authorized for the owner could wrap the token to
@@ -193,13 +289,24 @@ function readAccountPeek(raw) {
                     param.ownerWrappableDID,
                     param.controllerWrappableDID
                 ]);
-                await writeInTx((seam)=>seam.createCredential({
-                        providerName: param.providerName,
-                        ownerDID: param.ownerDID,
-                        ownerWrappableDID: param.ownerWrappableDID,
-                        controllerWrappableDID: param.controllerWrappableDID,
-                        credential: param.credential
-                    }));
+                try {
+                    await writeInTx((seam)=>seam.createCredential({
+                            providerName: param.providerName,
+                            ownerDID: param.ownerDID,
+                            ownerWrappableDID: param.ownerWrappableDID,
+                            controllerWrappableDID: param.controllerWrappableDID,
+                            credential: param.credential,
+                            authorizeKeyOwnerDID: async (ownerDID)=>{
+                                await authorizeWrite({
+                                    context,
+                                    subject: ownerDID
+                                });
+                                return true;
+                            }
+                        }));
+                } catch (error) {
+                    throw translateCredentialError(error);
+                }
                 return null;
             },
             'credential/refresh': async (context)=>{
@@ -208,9 +315,44 @@ function readAccountPeek(raw) {
                     context,
                     subject: param.ownerDID
                 });
+                await localWrite(context);
                 await writeInTx((seam)=>seam.setCredential(param.providerName, param.ownerDID, param.credential));
                 return null;
             },
+            'credential/refresh-entry': async (context)=>{
+                const param = context.param;
+                await authorizeWrite({
+                    context,
+                    subject: param.ownerDID
+                });
+                await localWrite(context);
+                requireLocalGrantAddress(param);
+                return writeInTx(async (seam)=>{
+                    // The authorized alias must still name the entry being refreshed.
+                    const ref = await seam.getVersionedCredentialRef(param.providerName, param.ownerDID);
+                    if (ref?.entryID !== param.entryID) return 'absent';
+                    return param.expectedVersion == null ? seam.setCredentialForEntry(param) : seam.setCredentialForEntryIfUnchanged({
+                        ...param,
+                        expectedVersion: param.expectedVersion
+                    });
+                });
+            },
+            'credential/adopt-grant': async (context)=>{
+                const param = context.param;
+                if (normalizeDID(param.toDeviceDID) !== localDeviceDID) {
+                    throw new ServiceAuthorizationError('The destination must be this device');
+                }
+                try {
+                    const keyOwnerDID = await readSeam.getGrantKeyOwnerDID(param);
+                    await authorizeWrite({
+                        context,
+                        subject: keyOwnerDID
+                    });
+                    return await readSeam.adoptCredentialGrant(param, keyOwnerDID);
+                } catch (error) {
+                    throw translateCredentialError(error);
+                }
+            },
             'credential/delete': async (context)=>{
                 const param = context.param;
                 await authorizeWrite({
@@ -226,6 +368,7 @@ function readAccountPeek(raw) {
                     context,
                     subject: param.ownerDID
                 }); // Gate A
+                await localWrite(context);
                 try {
                     await writeInTx((seam)=>seam.bindAlias(param.providerName, param.ownerDID, param.entryID));
                 } catch (err) {
@@ -237,10 +380,14 @@ function readAccountPeek(raw) {
         params.registerProvider('service', {
             name: 'credential',
             handlers,
+            protocol: credentialServiceProtocol,
             accessRules: {
                 'credential/get': {
                     allow: true
                 },
+                'credential/get-ref': {
+                    allow: true
+                },
                 'credential/peek': {
                     allow: true
                 },
@@ -253,6 +400,12 @@ function readAccountPeek(raw) {
                 'credential/refresh': {
                     allow: true
                 },
+                'credential/refresh-entry': {
+                    allow: true
+                },
+                'credential/adopt-grant': {
+                    allow: true
+                },
                 'credential/delete': {
                     allow: true
                 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/plugin-credential",
-  "version": "0.17.4",
+  "version": "0.18.0",
   "license": "see LICENSE.md",
   "sideEffects": false,
   "type": "module",
@@ -14,30 +14,30 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kokuin/token": "^0.5.0",
-    "@kubun/credential": "^0.17.4",
-    "@kubun/db": "^0.17.0",
-    "@kubun/engine": "^0.17.2",
-    "@kubun/graphql": "^0.17.2",
-    "@kubun/hlc": "^0.17.0",
-    "@kubun/id": "^0.17.0",
-    "@kubun/plugin-service-api": "^0.17.1",
-    "@kubun/plugin-service-server": "^0.17.1",
-    "@kubun/protocol": "^0.17.2",
-    "@kubun/store-credential": "^0.17.4",
-    "@sozai/codec": "^0.4.0",
+    "@kokuin/token": "^0.5.1",
+    "@kubun/credential": "^0.18.0",
+    "@kubun/db": "^0.18.0",
+    "@kubun/engine": "^0.18.0",
+    "@kubun/graphql": "^0.18.0",
+    "@kubun/hlc": "^0.18.0",
+    "@kubun/id": "^0.18.0",
+    "@kubun/plugin-service-api": "^0.18.0",
+    "@kubun/plugin-service-server": "^0.18.0",
+    "@kubun/protocol": "^0.18.0",
+    "@kubun/service-credential-api": "^0.18.0",
+    "@kubun/store-credential": "^0.18.0",
+    "@sozai/codec": "^0.4.3",
     "@sozai/runtime": "^0.1.0",
     "graphql": "^17.0.2"
   },
   "devDependencies": {
-    "@enkaku/client": "^0.21.2",
-    "@enkaku/transport": "^0.21.0",
-    "@kokuin/capability": "^0.3.0",
+    "@enkaku/client": "^0.21.5",
+    "@enkaku/transport": "^0.21.5",
+    "@kokuin/capability": "^0.4.2",
     "@kokuin/controller": "^0.1.0",
-    "@kubun/db-better-sqlite": "^0.17.0",
-    "@kubun/service-credential-api": "^0.17.2",
-    "@kubun/store-controller": "^0.17.0",
-    "@kubun/store-graph": "^0.17.1",
+    "@kubun/db-better-sqlite": "^0.18.0",
+    "@kubun/store-controller": "^0.18.0",
+    "@kubun/store-graph": "^0.18.0",
     "@kubun/test-utils": "^0.0.0"
   },
   "publishConfig": {