@kubun/service-credential-api 0.17.1 → 0.17.2

package/lib/adapter.d.ts

@@ -1,10 +1,25 @@
-import type { Client } from '@enkaku/client';
-import type { AliasBindingCredentialProvider, CredentialProvider } from '@kubun/credential-types';
+import { type Client } from '@enkaku/client';
+import type { AliasBindingCredentialProvider, CredentialProvider, ProviderAccount } from '@kubun/credential-types';
 import type { CredentialServiceProtocol } from './index.js';
+/**
+ * What a storage-only account peek discloses: the provider account and the
+ * scopes the credential was granted (absent from a server that predates
+ * them), nothing else.
+ */
+export type CredentialAccountPeek = {
+    providerAccount: ProviderAccount | null;
+    scopes?: Array<string>;
+};
 export type CredentialProviderWithProvenance = CredentialProvider & {
+    /**
+     * Storage-only, non-refreshing read of the stored credential's provider
+     * account only — no token material. Optional on the type so a provider that
+     * cannot offer one simply omits it; the service adapter always implements it.
+     */
+    peekAccount?(providerName: string, ownerDID: string): Promise<CredentialAccountPeek | null>;
     getCredentialProvenance(providerName: string, ownerDID: string): Promise<{
         updatedAt: string | null;
         writerDID: string | null;
     } | null>;
 };
-export declare function toCredentialProvider(client: Client<CredentialServiceProtocol>): CredentialProviderWithProvenance & AliasBindingCredentialProvider;
+export declare function toCredentialProvider(client: Client<CredentialServiceProtocol>): CredentialProviderWithProvenance & AliasBindingCredentialProvider & Required<Pick<CredentialProviderWithProvenance, 'peekAccount'>>;

package/lib/adapter.js

@@ -3,7 +3,10 @@
 // single `credential-provider`. It reuses the exact encoding the local
 // `DBCredentialProvider` writes, so a credential minted through the service reads
 // back byte-identical to one minted standalone.
+import { RequestError } from '@enkaku/client';
+import { ErrorCodes } from '@enkaku/protocol';
 import { deserializeCredential, serializeCredential } from '@kubun/credential';
+import { CredentialPeekUnsupportedError } from './errors.js';
 export function toCredentialProvider(client) {
     return {
         async get (providerName, ownerDID) {
@@ -15,6 +18,37 @@ export function toCredentialProvider(client) {
             });
             return raw == null ? null : deserializeCredential(raw);
         },
+        async peekAccount (providerName, ownerDID) {
+            let peeked;
+            try {
+                peeked = await client.request('credential/peek', {
+                    param: {
+                        providerName,
+                        ownerDID
+                    }
+                });
+            } catch (err) {
+                // Every current server grants `credential/peek` to any verified issuer
+                // (the subject authorizer answers a denial with `null`), so an access
+                // denial here most likely means the server does not serve the
+                // procedure — though a caller token that is expired or revoked is
+                // denied the same way. Either way no storage-only read is available.
+                if (err instanceof RequestError && err.code === ErrorCodes.ACCESS_DENIED) {
+                    // biome-ignore lint/style/useErrorCause: cause is forwarded to super via the options arg
+                    throw new CredentialPeekUnsupportedError({
+                        cause: err
+                    });
+                }
+                throw err;
+            }
+            if (peeked == null) return null;
+            return {
+                providerAccount: peeked.providerAccount ?? null,
+                ...peeked.scopes != null ? {
+                    scopes: peeked.scopes
+                } : {}
+            };
+        },
         async set ({ providerName, ownerDID, credential, ownerWrappableDID, controllerWrappableDID }) {
             // Create-vs-refresh dispatches on the owner's wrappable DID, mirroring
             // `DBCredentialProvider.set`: present ⇒ the mint (which fixes who can read),

package/lib/errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The error code `peekAccount` rejects with when the credential service
+ * denies access to `credential/peek`. The usual cause is a server that
+ * predates the procedure — its access rules deny what it does not serve — but
+ * an access denial is not specific to that: an expired or revoked caller
+ * token is denied the same way. A consumer treats it as "no storage-only read
+ * available" (and may prompt reauthorization), never as a transient failure.
+ */
+export declare const CREDENTIAL_PEEK_UNSUPPORTED = "CREDENTIAL_PEEK_UNSUPPORTED";
+/**
+ * Raised by `peekAccount` when the credential service denies
+ * `credential/peek` — see {@link CREDENTIAL_PEEK_UNSUPPORTED}.
+ */
+export declare class CredentialPeekUnsupportedError extends Error {
+    #private;
+    constructor(options?: ErrorOptions);
+    get code(): typeof CREDENTIAL_PEEK_UNSUPPORTED;
+}

package/lib/errors.js

@@ -0,0 +1,22 @@
+/**
+ * The error code `peekAccount` rejects with when the credential service
+ * denies access to `credential/peek`. The usual cause is a server that
+ * predates the procedure — its access rules deny what it does not serve — but
+ * an access denial is not specific to that: an expired or revoked caller
+ * token is denied the same way. A consumer treats it as "no storage-only read
+ * available" (and may prompt reauthorization), never as a transient failure.
+ */ export const CREDENTIAL_PEEK_UNSUPPORTED = 'CREDENTIAL_PEEK_UNSUPPORTED';
+/**
+ * Raised by `peekAccount` when the credential service denies
+ * `credential/peek` — see {@link CREDENTIAL_PEEK_UNSUPPORTED}.
+ */ export class CredentialPeekUnsupportedError extends Error {
+    #code;
+    constructor(options){
+        super('CREDENTIAL_PEEK_UNSUPPORTED: the credential service does not serve credential/peek', options);
+        this.name = 'CredentialPeekUnsupportedError';
+        this.#code = CREDENTIAL_PEEK_UNSUPPORTED;
+    }
+    get code() {
+        return this.#code;
+    }
+}

package/lib/index.d.ts

@@ -1,4 +1,5 @@
-export { type CredentialProviderWithProvenance, toCredentialProvider, } from './adapter.js';
+export { type CredentialAccountPeek, type CredentialProviderWithProvenance, toCredentialProvider, } from './adapter.js';
+export { CREDENTIAL_PEEK_UNSUPPORTED, CredentialPeekUnsupportedError } from './errors.js';
 export declare const credentialServiceProtocol: {
     readonly 'credential/get': {
         readonly type: "request";
@@ -23,6 +24,56 @@ export declare const credentialServiceProtocol: {
             }];
         };
     };
+    readonly 'credential/peek': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly providerName: {
+                    readonly type: "string";
+                };
+                readonly ownerDID: {
+                    readonly type: "string";
+                };
+            };
+            readonly required: readonly ["providerName", "ownerDID"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly anyOf: [{
+                readonly type: "object";
+                readonly properties: {
+                    readonly providerAccount: {
+                        readonly anyOf: readonly [{
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly iss: {
+                                    readonly type: "string";
+                                };
+                                readonly sub: {
+                                    readonly type: "string";
+                                };
+                            };
+                            readonly required: readonly ["iss", "sub"];
+                            readonly additionalProperties: false;
+                        }, {
+                            readonly type: "null";
+                        }];
+                    };
+                    readonly scopes: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+                readonly required: readonly ["providerAccount"];
+                readonly additionalProperties: false;
+            }, {
+                readonly type: "null";
+            }];
+        };
+    };
     readonly 'credential/provenance': {
         readonly type: "request";
         readonly param: {

package/lib/index.js

@@ -5,6 +5,7 @@
 // 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';
 // 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
@@ -42,6 +43,82 @@ export const credentialServiceProtocol = {
             ]
         }
     },
+    // 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
+    // reads its vault and never runs a token refresh, so a consumer can pin the
+    // provider-account fingerprint without triggering provider network I/O.
+    // `null` when no credential is stored (or the read is denied);
+    // `providerAccount: null` when the stored credential captured none.
+    // Additive: a server that predates it rejects the procedure, and a consumer
+    // that needs a non-refreshing read must treat that as unavailable rather than
+    // fall back to `credential/get`.
+    'credential/peek': {
+        type: 'request',
+        param: {
+            type: 'object',
+            properties: {
+                providerName: {
+                    type: 'string'
+                },
+                ownerDID: {
+                    type: 'string'
+                }
+            },
+            required: [
+                'providerName',
+                'ownerDID'
+            ],
+            additionalProperties: false
+        },
+        result: {
+            anyOf: [
+                {
+                    type: 'object',
+                    properties: {
+                        providerAccount: {
+                            anyOf: [
+                                {
+                                    type: 'object',
+                                    properties: {
+                                        iss: {
+                                            type: 'string'
+                                        },
+                                        sub: {
+                                            type: 'string'
+                                        }
+                                    },
+                                    required: [
+                                        'iss',
+                                        'sub'
+                                    ],
+                                    additionalProperties: false
+                                },
+                                {
+                                    type: 'null'
+                                }
+                            ]
+                        },
+                        // Optional: a server that predates it omits it, and a consumer
+                        // then checks the grant against the credential it spends.
+                        scopes: {
+                            type: 'array',
+                            items: {
+                                type: 'string'
+                            }
+                        }
+                    },
+                    required: [
+                        'providerAccount'
+                    ],
+                    additionalProperties: false
+                },
+                {
+                    type: 'null'
+                }
+            ]
+        }
+    },
     'credential/provenance': {
         type: 'request',
         param: {

package/package.json

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