@kubun/service-credential-api 0.17.2 → 0.18.0

package/lib/adapter.d.ts

@@ -1,5 +1,5 @@
 import { type Client } from '@enkaku/client';
-import type { AliasBindingCredentialProvider, CredentialProvider, ProviderAccount } from '@kubun/credential-types';
+import type { AdoptGrantAPI, AliasBindingCredentialProvider, CredentialProvider, EntryPairedCredentialProvider, ProviderAccount, VersionedEntryCredentialProvider } from '@kubun/credential-types';
 import type { CredentialServiceProtocol } from './index.js';
 /**
  * What a storage-only account peek discloses: the provider account and the
@@ -22,4 +22,4 @@ export type CredentialProviderWithProvenance = CredentialProvider & {
         writerDID: string | null;
     } | null>;
 };
-export declare function toCredentialProvider(client: Client<CredentialServiceProtocol>): CredentialProviderWithProvenance & AliasBindingCredentialProvider & Required<Pick<CredentialProviderWithProvenance, 'peekAccount'>>;
+export declare function toCredentialProvider(client: Client<CredentialServiceProtocol>): CredentialProviderWithProvenance & AliasBindingCredentialProvider & EntryPairedCredentialProvider & VersionedEntryCredentialProvider & AdoptGrantAPI & Required<Pick<CredentialProviderWithProvenance, 'peekAccount'>>;

package/lib/adapter.js

@@ -6,7 +6,8 @@
 import { RequestError } from '@enkaku/client';
 import { ErrorCodes } from '@enkaku/protocol';
 import { deserializeCredential, serializeCredential } from '@kubun/credential';
-import { CredentialPeekUnsupportedError } from './errors.js';
+import { CredentialUpdateUnavailableError } from '@kubun/credential-types';
+import { CredentialPeekUnsupportedError, CredentialUnexpectedSupersededError } from './errors.js';
 export function toCredentialProvider(client) {
     return {
         async get (providerName, ownerDID) {
@@ -18,6 +19,80 @@ export function toCredentialProvider(client) {
             });
             return raw == null ? null : deserializeCredential(raw);
         },
+        async getCredentialRef (providerName, ownerDID) {
+            const ref = await client.request('credential/get-ref', {
+                param: {
+                    providerName,
+                    ownerDID
+                }
+            });
+            return ref == null ? null : {
+                credential: deserializeCredential(ref.credential),
+                entryID: ref.entryID
+            };
+        },
+        async getVersionedCredentialRef (providerName, ownerDID) {
+            const ref = await client.request('credential/get-ref', {
+                param: {
+                    providerName,
+                    ownerDID
+                }
+            });
+            return ref == null ? null : {
+                credential: deserializeCredential(ref.credential),
+                entryID: ref.entryID,
+                ...ref.version == null ? {} : {
+                    version: ref.version
+                }
+            };
+        },
+        setCredentialForEntryIfUnchanged ({ providerName, ownerDID, entryID, credential, expectedVersion }) {
+            return client.request('credential/refresh-entry', {
+                param: {
+                    providerName,
+                    ownerDID,
+                    entryID,
+                    credential: serializeCredential(credential),
+                    expectedVersion
+                }
+            });
+        },
+        async update (address, change) {
+            for(;;){
+                const ref = await client.request('credential/get-ref', {
+                    param: {
+                        providerName: address.providerName,
+                        ownerDID: address.ownerDID,
+                        deviceDID: address.deviceDID
+                    }
+                });
+                if (ref == null || ref.version == null) throw new CredentialUpdateUnavailableError();
+                const result = await client.request('credential/refresh-entry', {
+                    param: {
+                        providerName: address.providerName,
+                        ownerDID: address.ownerDID,
+                        deviceDID: address.deviceDID,
+                        entryID: ref.entryID,
+                        credential: serializeCredential(change(deserializeCredential(ref.credential))),
+                        expectedVersion: ref.version
+                    }
+                });
+                if (result === 'updated') return;
+                if (result === 'absent') throw new CredentialUpdateUnavailableError();
+            }
+        },
+        async setCredentialForEntry ({ providerName, ownerDID, entryID, credential }) {
+            const result = await client.request('credential/refresh-entry', {
+                param: {
+                    providerName,
+                    ownerDID,
+                    entryID,
+                    credential: serializeCredential(credential)
+                }
+            });
+            if (result === 'superseded') throw new CredentialUnexpectedSupersededError();
+            return result;
+        },
         async peekAccount (providerName, ownerDID) {
             let peeked;
             try {
@@ -97,6 +172,11 @@ export function toCredentialProvider(client) {
                     entryID
                 }
             });
+        },
+        async adoptCredentialGrant (params) {
+            await client.request('credential/adopt-grant', {
+                param: params
+            });
         }
     };
 }

package/lib/errors.d.ts

@@ -16,3 +16,10 @@ export declare class CredentialPeekUnsupportedError extends Error {
     constructor(options?: ErrorOptions);
     get code(): typeof CREDENTIAL_PEEK_UNSUPPORTED;
 }
+/** An unconditional entry write received a result reserved for versioned writes. */
+export declare const CREDENTIAL_UNEXPECTED_SUPERSEDED = "CREDENTIAL_UNEXPECTED_SUPERSEDED";
+export declare class CredentialUnexpectedSupersededError extends Error {
+    #private;
+    constructor();
+    get code(): typeof CREDENTIAL_UNEXPECTED_SUPERSEDED;
+}

package/lib/errors.js

@@ -20,3 +20,15 @@
         return this.#code;
     }
 }
+/** An unconditional entry write received a result reserved for versioned writes. */ export const CREDENTIAL_UNEXPECTED_SUPERSEDED = 'CREDENTIAL_UNEXPECTED_SUPERSEDED';
+export class CredentialUnexpectedSupersededError extends Error {
+    #code;
+    constructor(){
+        super('The credential service superseded an unconditional entry write');
+        this.name = 'CredentialUnexpectedSupersededError';
+        this.#code = CREDENTIAL_UNEXPECTED_SUPERSEDED;
+    }
+    get code() {
+        return this.#code;
+    }
+}

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 export { type CredentialAccountPeek, type CredentialProviderWithProvenance, toCredentialProvider, } from './adapter.js';
-export { CREDENTIAL_PEEK_UNSUPPORTED, CredentialPeekUnsupportedError } from './errors.js';
+export { CREDENTIAL_PEEK_UNSUPPORTED, CREDENTIAL_UNEXPECTED_SUPERSEDED, CredentialPeekUnsupportedError, CredentialUnexpectedSupersededError, } from './errors.js';
 export declare const credentialServiceProtocol: {
     readonly 'credential/get': {
         readonly type: "request";
@@ -24,6 +24,45 @@ export declare const credentialServiceProtocol: {
             }];
         };
     };
+    readonly 'credential/get-ref': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly providerName: {
+                    readonly type: "string";
+                };
+                readonly ownerDID: {
+                    readonly type: "string";
+                };
+                readonly deviceDID: {
+                    readonly type: "string";
+                };
+            };
+            readonly required: readonly ["providerName", "ownerDID"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly anyOf: [{
+                readonly type: "object";
+                readonly properties: {
+                    readonly credential: {
+                        readonly type: "string";
+                    };
+                    readonly entryID: {
+                        readonly type: "string";
+                    };
+                    readonly version: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: readonly ["credential", "entryID"];
+                readonly additionalProperties: false;
+            }, {
+                readonly type: "null";
+            }];
+        };
+    };
     readonly 'credential/peek': {
         readonly type: "request";
         readonly param: {
@@ -165,6 +204,73 @@ export declare const credentialServiceProtocol: {
             readonly type: "null";
         };
     };
+    readonly 'credential/refresh-entry': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly providerName: {
+                    readonly type: "string";
+                };
+                readonly ownerDID: {
+                    readonly type: "string";
+                };
+                readonly deviceDID: {
+                    readonly type: "string";
+                };
+                readonly entryID: {
+                    readonly type: "string";
+                };
+                readonly credential: {
+                    readonly type: "string";
+                };
+                readonly expectedVersion: {
+                    readonly type: "string";
+                };
+            };
+            readonly required: readonly ["providerName", "ownerDID", "entryID", "credential"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "string";
+            readonly enum: readonly ["updated", "absent", "superseded"];
+        };
+    };
+    readonly 'credential/adopt-grant': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly providerName: {
+                    readonly type: "string";
+                };
+                readonly ownerDID: {
+                    readonly type: "string";
+                };
+                readonly fromDeviceDID: {
+                    readonly type: "string";
+                };
+                readonly toDeviceDID: {
+                    readonly type: "string";
+                };
+                readonly sourceKeyOwnerDID: {
+                    readonly type: "string";
+                };
+            };
+            readonly required: readonly ["providerName", "ownerDID", "fromDeviceDID", "toDeviceDID"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly adopted: {
+                    readonly type: "boolean";
+                };
+            };
+            readonly required: readonly ["adopted"];
+            readonly additionalProperties: false;
+        };
+    };
     readonly 'credential/delete': {
         readonly type: "request";
         readonly param: {

package/lib/index.js

@@ -5,14 +5,15 @@
 // authenticated client into the `credential-provider` the connector registers, so
 // this package is no longer type-only.
 export { toCredentialProvider } from './adapter.js';
-export { CREDENTIAL_PEEK_UNSUPPORTED, CredentialPeekUnsupportedError } from './errors.js';
+export { CREDENTIAL_PEEK_UNSUPPORTED, CREDENTIAL_UNEXPECTED_SUPERSEDED, CredentialPeekUnsupportedError, CredentialUnexpectedSupersededError } from './errors.js';
 // Param↔seam mapping. `providerName`/`ownerDID` are the alias key the seam
 // resolves. `ownerDID` is ALSO the authorization subject: each handler passes it
 // to `context.authorize(ownerDID)` (the per-serve `callerMayActFor`), NOT the
 // Enkaku message `sub` — the host rejects a `sub` that differs from `iss`, so a
 // caller acting for another owner carries that owner in the param, not the
 // envelope. Serialized credential bytes cross as a UTF string; the vault stores
-// the ciphertext, never the plaintext. Writes ack with `null`.
+// the ciphertext, never the plaintext. Entry-scoped writes report their outcome;
+// the other writes ack with `null`.
 export const credentialServiceProtocol = {
     'credential/get': {
         type: 'request',
@@ -43,6 +44,54 @@ export const credentialServiceProtocol = {
             ]
         }
     },
+    'credential/get-ref': {
+        type: 'request',
+        param: {
+            type: 'object',
+            properties: {
+                providerName: {
+                    type: 'string'
+                },
+                ownerDID: {
+                    type: 'string'
+                },
+                deviceDID: {
+                    type: 'string'
+                }
+            },
+            required: [
+                'providerName',
+                'ownerDID'
+            ],
+            additionalProperties: false
+        },
+        result: {
+            anyOf: [
+                {
+                    type: 'object',
+                    properties: {
+                        credential: {
+                            type: 'string'
+                        },
+                        entryID: {
+                            type: 'string'
+                        },
+                        version: {
+                            type: 'string'
+                        }
+                    },
+                    required: [
+                        'credential',
+                        'entryID'
+                    ],
+                    additionalProperties: false
+                },
+                {
+                    type: 'null'
+                }
+            ]
+        }
+    },
     // Storage-only, non-refreshing read of the stored credential's provider
     // account and the scopes it was granted — and nothing else: no token
     // material crosses the wire. The server
@@ -234,6 +283,89 @@ export const credentialServiceProtocol = {
             type: 'null'
         }
     },
+    'credential/refresh-entry': {
+        type: 'request',
+        param: {
+            type: 'object',
+            properties: {
+                providerName: {
+                    type: 'string'
+                },
+                ownerDID: {
+                    type: 'string'
+                },
+                deviceDID: {
+                    type: 'string'
+                },
+                entryID: {
+                    type: 'string'
+                },
+                credential: {
+                    type: 'string'
+                },
+                expectedVersion: {
+                    type: 'string'
+                }
+            },
+            required: [
+                'providerName',
+                'ownerDID',
+                'entryID',
+                'credential'
+            ],
+            additionalProperties: false
+        },
+        result: {
+            type: 'string',
+            enum: [
+                'updated',
+                'absent',
+                'superseded'
+            ]
+        }
+    },
+    'credential/adopt-grant': {
+        type: 'request',
+        param: {
+            type: 'object',
+            properties: {
+                providerName: {
+                    type: 'string'
+                },
+                ownerDID: {
+                    type: 'string'
+                },
+                fromDeviceDID: {
+                    type: 'string'
+                },
+                toDeviceDID: {
+                    type: 'string'
+                },
+                sourceKeyOwnerDID: {
+                    type: 'string'
+                }
+            },
+            required: [
+                'providerName',
+                'ownerDID',
+                'fromDeviceDID',
+                'toDeviceDID'
+            ],
+            additionalProperties: false
+        },
+        result: {
+            type: 'object',
+            properties: {
+                adopted: {
+                    type: 'boolean'
+                }
+            },
+            required: [
+                'adopted'
+            ],
+            additionalProperties: false
+        }
+    },
     'credential/delete': {
         type: 'request',
         param: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/service-credential-api",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,10 +15,10 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@enkaku/client": "^0.21.2",
-    "@enkaku/protocol": "^0.21.1",
-    "@kubun/credential": "^0.17.3",
-    "@kubun/credential-types": "^0.17.2"
+    "@enkaku/client": "^0.21.5",
+    "@enkaku/protocol": "^0.21.5",
+    "@kubun/credential": "^0.18.0",
+    "@kubun/credential-types": "^0.18.0"
   },
   "publishConfig": {
     "access": "public"