@tinycloud/web-sdk 3.8.1-beta.2 → 3.9.0-beta.3

package/dist/credentials/account-holder.d.ts

@@ -0,0 +1,12 @@
+import { type HolderSigner } from "@tinycloud/node-sdk/credentials";
+/** Kid fragment for an account (EIP-191) holder key, as the witness expects it. */
+export declare const ACCOUNT_KID_FRAGMENT = "blockchainAccountId";
+/**
+ * Account (EIP-191) holder. The caller supplies `sign`, which must be the wallet's `personal_sign` over the
+ * exact bytes it is given. That is the one place the EIP-191 prefix is applied. This module adds no prefix.
+ * It verifies the returned 65-byte signature by recovering the signer over the same message, and refuses
+ * unless the recovered address equals the account. `did` must be did:pkh:eip155:1, canonicalised to EIP-55.
+ * Bytes outside the account-binding domain are refused before `sign` is called.
+ */
+export declare function createAccountHolderSigner(did: string, sign: (bytes: Uint8Array) => Promise<Uint8Array>): HolderSigner;
+//# sourceMappingURL=account-holder.d.ts.map

package/dist/credentials/held-source.d.ts

@@ -0,0 +1,52 @@
+import { type IKVService } from "@tinycloud/sdk-core";
+import { type EmailProofAcquireInput, type EmailProofAcquisition, type EmailProofOptions, type EmailProofPendingStore, type HolderSigner } from "@tinycloud/node-sdk/credentials";
+import { type HeldIssuerPolicy } from "./held-store";
+export type HeldSourceErrorCode = "held-store-listing-limit";
+/** Typed, non-retryable refusal. Its message carries no credential or email text. */
+export declare class HeldSourceError extends Error {
+    readonly code: HeldSourceErrorCode;
+    readonly retryable = false;
+    constructor(code: HeldSourceErrorCode, message: string);
+}
+export interface HeldAcquireInput extends HeldIssuerPolicy {
+    readonly kv: IKVService;
+    /** Email address to prove. Matched case-insensitively against stored records. */
+    readonly address: string;
+    /** Account holder. Its did must be did:pkh:eip155; its signer is supplied by the caller. */
+    readonly holder: HolderSigner;
+    /** Session principal, when one exists. Must be the same account as `holder`. */
+    readonly sessionDid?: string;
+    /** Caller-supplied code source. Not hard-wired here. */
+    readonly getCode: NonNullable<EmailProofAcquireInput["getCode"]>;
+    readonly pendingStore?: EmailProofPendingStore;
+    readonly fetch?: EmailProofOptions["fetch"];
+    readonly signal?: EmailProofOptions["signal"];
+    readonly now?: () => Date;
+}
+export interface HeldCredentialResult {
+    /** The verified SD-JWT, as stored. */
+    readonly credential: string;
+    /** Canonical account owner: did:pkh:eip155:<chain>:<EIP-55 address>. */
+    readonly holderDid: string;
+    readonly expiresAt: Date;
+}
+/** Acquisition step. Production passes `acquireEmailProof`; tests inject a fake to reach the success branch. */
+export type HeldAcquireStep = (input: EmailProofAcquireInput) => Promise<EmailProofAcquisition>;
+/**
+ * Returns a verified, stored held credential for the account and email.
+ * Order: owner canonicalisation, session match, reuse lookup, acquisition, store-on-issue.
+ * Stored records are returned without network. A store failure after verification is VERIFIED_NOT_SAVED.
+ */
+export declare function acquireHeldCredential(input: HeldAcquireInput): Promise<HeldCredentialResult>;
+/**
+ * `acquireHeldCredential` with the acquisition step injected. Production calls `acquireHeldCredential`.
+ * This seam exists so the issued branch can be exercised while the held profile pin stays disabled.
+ */
+export declare function acquireHeldCredentialWith(input: HeldAcquireInput, acquire: HeldAcquireStep): Promise<HeldCredentialResult>;
+/**
+ * Scopes a shared pending store to one held owner. The did:key email flow uses the same store, so a held
+ * acquisition must never resume, prompt for, or delete a pending request of another profile or holder.
+ * Pending requests are matched by profile and by holder principal, never by string equality.
+ */
+export declare function scopeHeldPendingStore(store: EmailProofPendingStore | undefined, holderDid: string, now: () => Date): EmailProofPendingStore | undefined;
+//# sourceMappingURL=held-source.d.ts.map

package/dist/credentials/held-store.d.ts

@@ -0,0 +1,138 @@
+import { CredentialError, type IKVService } from "@tinycloud/sdk-core";
+import { type HeldEmailCredentialOptions, type VerifiedHeldEmailCredential } from "@tinycloud/sdk-core/held-credentials";
+/** A held record whose verified expiry is within this many milliseconds is not offered; the caller re-acquires. */
+export declare const HELD_REUSE_MARGIN_MS = 600000;
+/** Issuer policy for the S3.1 verifier. The owner and the clock are supplied per call. */
+export type HeldIssuerPolicy = Omit<HeldEmailCredentialOptions, "owner" | "now">;
+/**
+ * Stored shape. Only `credential` is trusted: every read re-verifies it, and no other stored field
+ * (email, expiry, subject) is read.
+ */
+export interface HeldCredentialRecord {
+    readonly type: "TinyCloudHeldCredential";
+    readonly version: 1;
+    readonly ownerDid: string;
+    readonly recordId: string;
+    readonly credentialDigest: string;
+    readonly credential: string;
+    readonly storedAt: string;
+}
+export interface HeldStorageReceipt {
+    readonly type: "TinyCloudHeldStorageReceipt";
+    readonly version: 1;
+    readonly ownerDid: string;
+    readonly recordId: string;
+    readonly recordDigest: string;
+    readonly storedAt: string;
+}
+/**
+ * A stored record that re-verified under the caller's policy, with the verifier's output.
+ * `record` is the raw stored value: only `verified` and the summary fields below are authoritative.
+ * `recordId`, `email`, `issuedAt`, `expiresAt` and `issuer` are a summary for display. They come from the
+ * re-verified credential and from the record key, never from any stored field other than `credential`.
+ */
+export interface HeldMatch {
+    readonly record: HeldCredentialRecord;
+    readonly verified: VerifiedHeldEmailCredential;
+    /** The record key's id: the digest the store derives from the credential and the owner. */
+    readonly recordId: string;
+    /** The disclosed email as the credential carries it. */
+    readonly email: string;
+    /** The signed `iat`. */
+    readonly issuedAt: Date;
+    /** The signed `exp`. */
+    readonly expiresAt: Date;
+    /** The issuer DID that signed the credential. */
+    readonly issuer: string;
+}
+/**
+ * Canonical account owner: `did:pkh:eip155:1:<EIP-55 address>`.
+ * Anything that is not a did:pkh (for example a did:key holder) is refused, and so is any chain other than 1.
+ */
+export declare function heldAccountOwner(ownerDid: unknown): string;
+/** Key prefix for one owner. Keyed by the lowercase address, so case variants of one owner share it. */
+export declare function heldPrefix(ownerDid: string): string;
+export declare function heldRecordKey(ownerDid: string, recordId: string): string;
+export declare function createHeldStorageReceipt(record: HeldCredentialRecord): Promise<HeldStorageReceipt>;
+/** Owner and holder compares use principal equality, never string equality. */
+export declare function verifyHeldStorageReceipt(record: HeldCredentialRecord, receipt: HeldStorageReceipt, ownerDid: string): Promise<boolean>;
+export interface StoreHeldCredentialInput extends HeldIssuerPolicy {
+    readonly kv: IKVService;
+    readonly ownerDid: unknown;
+    readonly sdJwt: unknown;
+    readonly now?: Date;
+}
+export interface StoreHeldCredentialResult {
+    readonly record: HeldCredentialRecord;
+    readonly receipt: HeldStorageReceipt;
+    readonly verified: VerifiedHeldEmailCredential;
+}
+/**
+ * Store-on-issue. Verifies the SD-JWT itself, writes one record under the owner's prefix, and reads
+ * it back. Refuses before any write unless the credential verifies, belongs to the owner, and stays
+ * outside the reuse margin. `verified` is the verifier's output for the stored credential.
+ */
+export declare function storeHeldCredential(input: StoreHeldCredentialInput): Promise<StoreHeldCredentialResult>;
+/** Listing refused beyond the page limit. Keeps the VERIFICATION_FAILED wire code; recovery callers test for this subclass. */
+export declare class HeldListingLimitError extends CredentialError {
+}
+export interface FindHeldCredentialInput extends HeldIssuerPolicy {
+    readonly kv: IKVService;
+    readonly ownerDid: unknown;
+    readonly email: string;
+    readonly now?: Date;
+}
+/**
+ * Owner-scoped read. Lists only `v1/held/<registryKey>/`, so `v1/records/` is never considered.
+ * Returns the verified record with the latest expiry that still clears the reuse margin, or undefined.
+ */
+export declare function findHeldCredential(input: FindHeldCredentialInput): Promise<HeldMatch | undefined>;
+export type ListHeldEmailCredentialsInput = Omit<FindHeldCredentialInput, "email"> & {
+    /** Accepted so a `FindHeldCredentialInput` can be passed as is. Ignored: the listing is never filtered by email. */
+    readonly email?: string;
+};
+/**
+ * Lists the account's own VALID held email credentials. Owner-only: it reads `v1/held/<registryKey>/` for the
+ * canonical `ownerDid` and nothing else, and refuses any owner that is not an Ethereum mainnet did:pkh.
+ *
+ * Returns every valid record, not one per email: no email filter and no "latest" pick. Expired records and
+ * records the verifier refuses (status other than none, issuer retired or not accepted, bad signature) are
+ * EXCLUDED. Validity is what `findHeldCredential` applies: re-verification plus the reuse margin. A record is
+ * listed only if it is valid for more than 10 more minutes, meaning its expiry is more than `HELD_REUSE_MARGIN_MS`
+ * after `now`. A record with exactly 10 minutes left is excluded, as in `findHeldCredential`, so the screen never
+ * offers a record that `findHeldCredential` or a presentation would refuse.
+ *
+ * Order: newest `issuedAt` first; equal `issuedAt` by ascending `recordId`. Returns `[]` when there are none.
+ *
+ * Throws if the store cannot be read; skips records that fail verification. A record that is corrupt,
+ * malformed or fails verification is skipped silently, never reported and never thrown. A store failure is
+ * not a bad record, so the screen can tell "none" from "unreachable": a `kv.get` or `kv.list` that throws
+ * propagates, and one that resolves not-ok is an `OFFLINE` CredentialError (a key that is gone by the time it
+ * is read, `KV_NOT_FOUND`, is skipped). A refused owner, or a listing that is truncated or beyond the page
+ * limit, also throws. `findHeldCredential` is looser: it reads a failed `kv.list` as "not found".
+ * Every returned summary field comes from the re-verified credential, never from other stored fields.
+ * `record` is the raw stored value; only the `verified` fields and the summary above are authoritative.
+ */
+export declare function listHeldEmailCredentials(input: ListHeldEmailCredentialsInput): Promise<readonly HeldMatch[]>;
+/**
+ * Deletes the named record key only. The recordId is validated first, so a caller-supplied value cannot
+ * address another key. Copies outside this store remain valid until their own expiry.
+ */
+export declare function deleteHeldCredential(input: {
+    readonly kv: IKVService;
+    readonly ownerDid: unknown;
+    readonly recordId: string;
+}): Promise<boolean>;
+export interface PruneHeldCredentialsInput extends HeldIssuerPolicy {
+    readonly kv: IKVService;
+    readonly ownerDid: unknown;
+    readonly now?: Date;
+}
+/**
+ * Refresh housekeeping for one owner. Deletes records whose signature verifies but whose expiry has
+ * passed, and for each email keeps only the verified record with the newest expiry. Unverifiable records
+ * are left in place: prune cannot tell a forgery from a policy mismatch, so it never deletes on that basis.
+ * Returns the keys actually removed.
+ */
+export declare function pruneHeldCredentials(input: PruneHeldCredentialsInput): Promise<readonly string[]>;
+//# sourceMappingURL=held-store.d.ts.map

package/dist/credentials-subpath.d.ts

@@ -3,4 +3,9 @@ export { interpretCredentialFlow } from "@tinycloud/node-sdk/credentials";
 export type { CredentialAcquisitionTransport, CredentialRequestState, CredentialSigningAdapter, PrimitiveStepHandler, PrimitiveStepResult, } from "@tinycloud/node-sdk/credentials";
 export { acquireEmailProof, completeEmailProof, createEd25519HolderSigner, createMemoryEmailProofPendingStore, EmailProofError, requestEmailProofCode, verifyStoredEmailProof, } from "@tinycloud/node-sdk/credentials";
 export type { EmailProofAcquireInput, EmailProofAcquisition, EmailProofErrorCode, EmailProofOptions, EmailProofPending, EmailProofPendingStore, EmailProofProfileId, EmailProofRequestInput, EmailProofResult, EmailProofStep, HolderAlgorithm, HolderSigner, StoredEmailProofInput, StoredEmailProofRecord, } from "@tinycloud/node-sdk/credentials";
+export { createAccountHolderSigner } from "./credentials/account-holder";
+export { findHeldCredential, listHeldEmailCredentials, storeHeldCredential, } from "./credentials/held-store";
+export type { FindHeldCredentialInput, HeldCredentialRecord, HeldIssuerPolicy, HeldMatch, HeldStorageReceipt, ListHeldEmailCredentialsInput, StoreHeldCredentialInput, } from "./credentials/held-store";
+export { acquireHeldCredential } from "./credentials/held-source";
+export type { HeldAcquireInput, HeldCredentialResult } from "./credentials/held-source";
 //# sourceMappingURL=credentials-subpath.d.ts.map