@kubun/credential-types 0.17.1 → 0.18.0

package/lib/index.d.ts

@@ -1,3 +1,9 @@
+export type ProviderAccount = {
+    /** OpenID issuer, e.g. `https://accounts.google.com`. */
+    iss: string;
+    /** Stable, opaque provider subject id. Never projected to the graph. */
+    sub: string;
+};
 export type Credential = {
     accessToken: string;
     refreshToken?: string;
@@ -5,7 +11,35 @@ export type Credential = {
     scopes: Array<string>;
     accountLabel?: string;
     metadata?: Record<string, unknown>;
+    /**
+     * Verified stable provider-account identity captured at OAuth completion.
+     * Lives only in the encrypted credential body; the graph sees only a derived
+     * non-reversible key. Preserved verbatim across token refresh.
+     */
+    providerAccount?: ProviderAccount;
+};
+export type GrantAddress = {
+    providerName: string;
+    ownerDID: string;
+    deviceDID: string;
+};
+export type AdoptGrantParams = {
+    providerName: string;
+    ownerDID: string;
+    fromDeviceDID: string;
+    toDeviceDID: string;
+    /** Required to resolve a no-alias grant that exists under multiple key owners. */
+    sourceKeyOwnerDID?: string;
 };
+export type AdoptGrantResult = {
+    adopted: boolean;
+};
+export type AdoptGrantAPI = {
+    adoptCredentialGrant(params: AdoptGrantParams): Promise<void>;
+};
+export declare class CredentialUpdateUnavailableError extends Error {
+    constructor();
+}
 export type CredentialProvider = {
     get(providerName: string, ownerDID: string): Promise<Credential | null>;
     /**
@@ -27,6 +61,7 @@ export type CredentialProvider = {
         controllerWrappableDID?: string;
     }): Promise<void>;
     delete(providerName: string, ownerDID: string): Promise<void>;
+    update?(address: GrantAddress, change: (current: Credential | null) => Credential): Promise<void>;
 };
 /**
  * Opt-in capability: point `(providerName, ownerDID)` at an entry the
@@ -54,3 +89,26 @@ export type EntryPairedCredentialProvider = {
         credential: Credential;
     }): Promise<'updated' | 'absent'>;
 };
+/**
+ * Opt-in capability over {@link EntryPairedCredentialProvider}: a read that also
+ * returns the entry's `version`, an opaque token that changes on every write, and
+ * a write that lands only while the entry is still at that version. A refresh
+ * writes back through it so a credential replaced while the token exchange was in
+ * flight (a new consent) is kept rather than overwritten: the write reports
+ * `'superseded'` instead. The check and the write are one atomic store call, so no
+ * lock spans the two.
+ */
+export type VersionedEntryCredentialProvider = {
+    getVersionedCredentialRef(providerName: string, ownerDID: string): Promise<{
+        credential: Credential;
+        entryID: string;
+        version?: string;
+    } | null>;
+    setCredentialForEntryIfUnchanged(params: {
+        providerName: string;
+        ownerDID: string;
+        entryID: string;
+        credential: Credential;
+        expectedVersion: string;
+    }): Promise<'updated' | 'absent' | 'superseded'>;
+};

package/lib/index.js

@@ -2,8 +2,9 @@
 // that stores/refreshes it. Kept in this leaf package so both the low-level
 // `@kubun/connector` (which consumes the port) and `@kubun/credential` (which
 // implements it) can depend on the types without depending on each other.
-/**
- * Opt-in capability: read and write a credential together with the entryID
- * it resolves to, so a caller can target that entry directly on a
- * subsequent write without re-resolving the alias.
- */ export { };
+export class CredentialUpdateUnavailableError extends Error {
+    constructor(){
+        super('A current credential entry version is required for a conditional update');
+        this.name = 'CredentialUpdateUnavailableError';
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/credential-types",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,