@kubun/credential 0.17.3 → 0.18.0

package/lib/api.d.ts

@@ -1,16 +1,32 @@
 import { type MethodRegistry } from '@kokuin/token';
+import type { AdoptGrantParams, AdoptGrantResult } from '@kubun/credential-types';
 import type { StoreProvider } from '@kubun/db';
 import type { Logger } from '@kubun/logger';
 import type { CredentialManager } from './manager.js';
 /**
- * The credential seam: resolves its `(providerName, ownerDID) → entryID` pointer
+ * The credential seam: resolves its `(providerName, ownerDID, deviceDID) → entryID` pointer
  * through the alias layer of the credential store, and its entries through a
  * `CredentialManager`. Every `ownerDID` is normalized before it reaches the
  * alias, so an un-normalized equality key cannot split one account across two
  * rows: a credential invisible under one spelling and un-revokable under the
  * other.
  */
+export type CreateCredentialParams = {
+    providerName: string;
+    ownerDID: string;
+    ownerWrappableDID: string;
+    controllerWrappableDID?: string;
+    credential: string;
+    /** Service authority check before replacing an existing grant. */
+    authorizeKeyOwnerDID?: (ownerDID: string) => Promise<boolean>;
+};
+export type AdoptGrantRecoveryParams = AdoptGrantParams & {
+    sourceKeyOwnerDID?: string;
+};
 export type CredentialAPI = {
+    getLocalDeviceDID: () => string;
+    getGrantKeyOwnerDID: (params: AdoptGrantRecoveryParams) => Promise<string>;
+    adoptCredentialGrant: (params: AdoptGrantRecoveryParams, authorizedKeyOwnerDID?: string) => Promise<AdoptGrantResult>;
     getCredential: (providerName: string, ownerDID: string) => Promise<string | null>;
     getCredentialProvenance: (providerName: string, ownerDID: string) => Promise<{
         updatedAt: string | null;
@@ -29,21 +45,15 @@ export type CredentialAPI = {
      * with no owner in hand would mint one wrapped to the server alone — locking
      * the account owner out of their own credential with nothing failing.
      */
-    createCredential: (params: {
-        providerName: string;
-        ownerDID: string;
-        ownerWrappableDID: string;
-        controllerWrappableDID?: string;
-        credential: string;
-    }) => Promise<void>;
+    createCredential: (params: CreateCredentialParams) => Promise<void>;
     deleteCredential: (providerName: string, ownerDID: string) => Promise<void>;
     /**
-     * Point `(providerName, ownerDID)` at an entry this device already holds,
+     * Point this device's `(providerName, ownerDID, deviceDID)` alias at an entry it 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
+     * Gate B first: the signed grant and its key must name `ownerDID`. The vault
+     * can decrypt entries 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
@@ -53,18 +63,14 @@ export type CredentialAPI = {
     /**
      * The normalized owner DIDs that currently hold a credential for `providerName`.
      *
-     * A credential is pointed at by an alias keyed `(providerName, normalizeDID(
-     * ownerDID))`, so the alias keys under a provider namespace are exactly its
-     * authenticated owners — already normalized, so a caller can key sync state or
-     * a schedule on them directly. Empty when no owner holds one.
+     * A credential is pointed at by an alias keyed by provider, normalized owner,
+     * and the local identity's DID. The owners under a provider namespace are
+     * already normalized, so a caller can key sync state on them directly.
      */
     listSubjects: (providerName: string) => Promise<Array<string>>;
     /**
-     * The controller resolvers for this API's (request-scoped) transaction
-     * provider — the exact `methods` the credential mint passes to `createKey`.
-     * Exposed so the OAuth pre-flight can ask `canWrapTo` with the same resolver
-     * the mint uses, rather than failing closed on a `did:kokuin:` owner whose
-     * agreement key is resolvable only through the controller resolver.
+     * Pull-capable controller resolvers for OAuth pre-flight `canWrapTo`.
+     * Minting uses their local-only counterparts after recipients are prewarmed.
      */
     getControllerMethods: () => MethodRegistry;
     /**
@@ -87,6 +93,29 @@ export type CredentialAPI = {
         entryID: string;
         credential: string;
     }) => Promise<'updated' | 'absent'>;
+    /**
+     * As `getCredentialRef`, plus the entry's `version`: an opaque token that
+     * changes on every write to the entry, read before the credential itself so it
+     * is never newer than the credential returned with it.
+     */
+    getVersionedCredentialRef: (providerName: string, ownerDID: string) => Promise<{
+        credential: string;
+        entryID: string;
+        version: string;
+    } | null>;
+    /**
+     * As `setCredentialForEntry`, and also only while the entry is still at
+     * `expectedVersion` (from `getVersionedCredentialRef`). A write that landed in
+     * between is kept and reported as `'superseded'`; the check and the write are
+     * one atomic store call inside whatever transaction the API runs in.
+     */
+    setCredentialForEntryIfUnchanged: (params: {
+        providerName: string;
+        ownerDID: string;
+        entryID: string;
+        credential: string;
+        expectedVersion: string;
+    }) => Promise<'updated' | 'absent' | 'superseded'>;
 };
 export type CreateCredentialAPIParams = {
     stores: StoreProvider;
@@ -96,16 +125,18 @@ export type CreateCredentialAPIParams = {
      * that provider is the transaction and a manager built over the base one
      * would read outside it.
      */
-    getCredentialManager: (stores: StoreProvider) => Promise<CredentialManager>;
+    getCredentialManager: (stores: StoreProvider, recoveryChecked?: boolean) => Promise<CredentialManager>;
     /** The engine's own DID, in a form that can be encrypted to. */
     serverWrappableDID: string;
-    /**
-     * Resolvers for wrapping recipients that carry no key material of their own
-     * (`did:kokuin:`), scoped to the request's transaction provider so a resolve
-     * reads the mutation's tx, never a second connection. A self-contained
-     * recipient resolves with an empty registry, so callers with no controller
-     * recipient in play still pass `() => []`.
-     */
-    getControllerMethods: (stores: StoreProvider) => MethodRegistry;
+    /** Resolvers for controller recipients; minting must use local-only methods. */
+    getControllerMethods: (stores: StoreProvider, options?: {
+        localOnly?: boolean;
+    }) => MethodRegistry;
+    /** The caller already resolved recipients before opening its ambient transaction. */
+    wrappingRecipientsPrewarmed?: boolean;
+    /** The current controller of an account device, if one is locally verifiable. */
+    resolveControllerOfOwner?: (ownerDID: string, stores: StoreProvider) => Promise<string | null>;
+    /** Authority used by local providers before replacing an existing grant. */
+    authorizeKeyOwnerDID?: (ownerDID: string, stores: StoreProvider) => Promise<boolean>;
 };
 export declare function createCredentialAPI(params: CreateCredentialAPIParams): CredentialAPI;