@tinycloud/node-sdk 3.9.0-beta.3 → 3.9.0-beta.5

package/dist/{email-proof-D0r_WShV.d.cts → email-proof-B4DRizIL.d.cts}

@@ -1,4 +1,5 @@
 import { IssuedCredentialEnvelope, VerifiedCredential, CredentialFlowDescriptor, StoredCredentialRecord, CredentialRequirement } from '@tinycloud/sdk-core';
+import { VerifiedHeldEmailCredential } from '@tinycloud/sdk-core/held-credentials';
 
 declare const EMAIL_PROOF_CREDENTIAL_TYPE: {
     readonly id: "opencredentials.email/v1";
@@ -22,17 +23,18 @@ type EmailProofStep = "request" | "code" | "credential" | "session";
  * | RATE_LIMITED            | witness     | witness `recoverable` flag decides (defaults to true); retryAfterMs set |
  * | ISSUER_UNAVAILABLE      | true        | transient issuer outage (503); witness flag is honoured |
  * | NETWORK                 | true        | transport failure or step timeout; pending kept |
- * | PROFILE_UNAVAILABLE     | false       | catalog or descriptor does not match the pinned profile |
+ * | PROFILE_UNAVAILABLE     | false       | catalog or descriptor does not match the pinned profile, or (local, no witness contacted) the profile is not enabled |
  * | CODE_REJECTED           | true        | wrong code; witness flag decides whether another attempt is allowed |
  * | CODE_ATTEMPTS_EXHAUSTED | false       | witness proof-attempt budget spent; pending is dead |
  * | SIGNATURE_REJECTED      | true        | holder binding rejected; same pending may be retried |
  * | CREDENTIAL_INVALID      | false       | issued credential failed local verification |
  * | SESSION_EXPIRED         | false       | pending window or server expiry has passed |
  * | SESSION_INVALID         | false       | pending does not match holder, descriptor, or requirement |
+ * | CLIENT_CLOCK_SKEW       | false       | device clock more than 5 min behind the witness; no mail sent; fix the clock and start again |
  * | CANCELED                | false       | caller aborted; pending is deleted |
  * | FAILED                  | false       | unclassified failure; pending is deleted |
  */
-type EmailProofErrorCode = "ADDRESS_INVALID" | "HOLDER_INVALID" | "CODE_INVALID" | "RATE_LIMITED" | "ISSUER_UNAVAILABLE" | "NETWORK" | "PROFILE_UNAVAILABLE" | "CODE_REJECTED" | "CODE_ATTEMPTS_EXHAUSTED" | "SIGNATURE_REJECTED" | "CREDENTIAL_INVALID" | "SESSION_EXPIRED" | "SESSION_INVALID" | "CANCELED" | "FAILED";
+type EmailProofErrorCode = "ADDRESS_INVALID" | "HOLDER_INVALID" | "CODE_INVALID" | "RATE_LIMITED" | "ISSUER_UNAVAILABLE" | "NETWORK" | "PROFILE_UNAVAILABLE" | "CODE_REJECTED" | "CODE_ATTEMPTS_EXHAUSTED" | "SIGNATURE_REJECTED" | "CREDENTIAL_INVALID" | "SESSION_EXPIRED" | "SESSION_INVALID" | "CLIENT_CLOCK_SKEW" | "CANCELED" | "FAILED";
 /** Stable, redaction-safe error. The message never includes the code, verifier, or key material. */
 declare class EmailProofError extends Error {
     readonly name = "EmailProofError";
@@ -40,7 +42,8 @@ declare class EmailProofError extends Error {
     readonly code: EmailProofErrorCode;
     readonly retryAfterMs: number | undefined;
     readonly recoverable: boolean;
-    constructor(step: EmailProofStep, code: EmailProofErrorCode, retryAfterMs?: number, recoverable?: boolean);
+    /** `message` overrides the code's text for one refusal whose cause the shared text would misdescribe. It never carries request data. */
+    constructor(step: EmailProofStep, code: EmailProofErrorCode, retryAfterMs?: number, recoverable?: boolean, message?: string);
 }
 type HolderAlgorithm = "EdDSA" | "EIP191";
 /**
@@ -63,6 +66,14 @@ interface HolderSigner {
 declare function createEd25519HolderSigner(did: string, sign: (bytes: Uint8Array) => Promise<Uint8Array>): HolderSigner;
 /** Options shared by the public steps. Issuer keys are never caller-supplied. */
 interface EmailProofOptions {
+    /**
+     * Per-call opt-in for the held profile `tinycloud.email-held/v1`. Only the literal `true` counts, it enables the held
+     * profile for this call alone (never stored in a pending, never read from the environment), and it is ignored for any other
+     * profile. Without it a held request is refused PROFILE_UNAVAILABLE before any network call. Nothing else can be supplied with
+     * it: the origin, issuer key and descriptor digest are compiled pins. The default 60 s step signal spans the wallet prompt in
+     * `completeEmailProof` for an account holder: pass a `signal` bounded by the request `expiresAt` if the user may take longer.
+     */
+    readonly allowHeldProfile?: true;
     readonly fetch?: typeof fetch;
     readonly signal?: AbortSignal;
     readonly now?: () => Date;
@@ -90,6 +101,8 @@ interface EmailProofPending {
     readonly openerOrigin: string;
     readonly createdAt: string;
     readonly expiresAt: string;
+    /** Held only: `expiresAt` of the create response (the witness's own deadline). The signed binding must carry it. */
+    readonly serverExpiresAt?: string;
 }
 /** Holds pending requests keyed by requestId. Implementations must never return an expired request from `findLive`. */
 interface EmailProofPendingStore {
@@ -104,13 +117,18 @@ interface EmailProofPendingStore {
 declare function createMemoryEmailProofPendingStore(): EmailProofPendingStore;
 interface EmailProofResult {
     readonly envelope: IssuedCredentialEnvelope;
-    readonly verified: VerifiedCredential;
+    /** The ticket verifier's result, or for the held profile (`envelope.profile.id`) the held verifier's. */
+    readonly verified: VerifiedCredential | VerifiedHeldEmailCredential;
     readonly credentialId: string;
     readonly issuedAt: string;
     readonly expiresAt: string;
     /** The descriptor the verifier checked against. Stored alongside the credential for offline re-verification. */
     readonly descriptor: CredentialFlowDescriptor;
 }
+/** True for a ticket (did:key) result, whose `verified` is the ticket verifier's output. The held profile's result carries the held verifier's. */
+declare function isTicketEmailProofResult(result: EmailProofResult): result is EmailProofResult & {
+    readonly verified: VerifiedCredential;
+};
 interface EmailProofAcquireInput extends EmailProofRequestInput {
     /** Supplies the 8-digit code. Omit to only request one; the pending request is returned for a later call. */
     readonly getCode?: (context: {
@@ -174,4 +192,4 @@ type StoredEmailProofInput = {
  */
 declare function verifyStoredEmailProof(input: StoredEmailProofInput): Promise<VerifiedCredential>;
 
-export { DEFAULT_EMAIL_PROOF_PROFILE as D, EMAIL_PROOF_CREDENTIAL_TYPE as E, type HolderAlgorithm as H, type StoredEmailProofInput as S, EMAIL_PROOF_PENDING_MAX_MS as a, type EmailProofAcquireInput as b, type EmailProofAcquisition as c, EmailProofError as d, type EmailProofErrorCode as e, type EmailProofOptions as f, type EmailProofPending as g, type EmailProofPendingStore as h, type EmailProofProfileId as i, type EmailProofRequestInput as j, type EmailProofResult as k, type EmailProofStep as l, type HolderSigner as m, type StoredEmailProofRecord as n, acquireEmailProof as o, completeEmailProof as p, createEd25519HolderSigner as q, createMemoryEmailProofPendingStore as r, emailProofRequirement as s, requestEmailProofCode as t, verifyStoredEmailProof as v };
+export { DEFAULT_EMAIL_PROOF_PROFILE as D, type EmailProofPendingStore as E, type HolderAlgorithm as H, type StoredEmailProofInput as S, type EmailProofPending as a, EMAIL_PROOF_CREDENTIAL_TYPE as b, EMAIL_PROOF_PENDING_MAX_MS as c, type EmailProofAcquireInput as d, type EmailProofAcquisition as e, EmailProofError as f, type EmailProofErrorCode as g, type EmailProofOptions as h, type EmailProofProfileId as i, type EmailProofRequestInput as j, type EmailProofResult as k, type EmailProofStep as l, type HolderSigner as m, type StoredEmailProofRecord as n, acquireEmailProof as o, completeEmailProof as p, createEd25519HolderSigner as q, createMemoryEmailProofPendingStore as r, emailProofRequirement as s, isTicketEmailProofResult as t, requestEmailProofCode as u, verifyStoredEmailProof as v };

package/dist/{email-proof-D0r_WShV.d.ts → email-proof-B4DRizIL.d.ts}

@@ -1,4 +1,5 @@
 import { IssuedCredentialEnvelope, VerifiedCredential, CredentialFlowDescriptor, StoredCredentialRecord, CredentialRequirement } from '@tinycloud/sdk-core';
+import { VerifiedHeldEmailCredential } from '@tinycloud/sdk-core/held-credentials';
 
 declare const EMAIL_PROOF_CREDENTIAL_TYPE: {
     readonly id: "opencredentials.email/v1";
@@ -22,17 +23,18 @@ type EmailProofStep = "request" | "code" | "credential" | "session";
  * | RATE_LIMITED            | witness     | witness `recoverable` flag decides (defaults to true); retryAfterMs set |
  * | ISSUER_UNAVAILABLE      | true        | transient issuer outage (503); witness flag is honoured |
  * | NETWORK                 | true        | transport failure or step timeout; pending kept |
- * | PROFILE_UNAVAILABLE     | false       | catalog or descriptor does not match the pinned profile |
+ * | PROFILE_UNAVAILABLE     | false       | catalog or descriptor does not match the pinned profile, or (local, no witness contacted) the profile is not enabled |
  * | CODE_REJECTED           | true        | wrong code; witness flag decides whether another attempt is allowed |
  * | CODE_ATTEMPTS_EXHAUSTED | false       | witness proof-attempt budget spent; pending is dead |
  * | SIGNATURE_REJECTED      | true        | holder binding rejected; same pending may be retried |
  * | CREDENTIAL_INVALID      | false       | issued credential failed local verification |
  * | SESSION_EXPIRED         | false       | pending window or server expiry has passed |
  * | SESSION_INVALID         | false       | pending does not match holder, descriptor, or requirement |
+ * | CLIENT_CLOCK_SKEW       | false       | device clock more than 5 min behind the witness; no mail sent; fix the clock and start again |
  * | CANCELED                | false       | caller aborted; pending is deleted |
  * | FAILED                  | false       | unclassified failure; pending is deleted |
  */
-type EmailProofErrorCode = "ADDRESS_INVALID" | "HOLDER_INVALID" | "CODE_INVALID" | "RATE_LIMITED" | "ISSUER_UNAVAILABLE" | "NETWORK" | "PROFILE_UNAVAILABLE" | "CODE_REJECTED" | "CODE_ATTEMPTS_EXHAUSTED" | "SIGNATURE_REJECTED" | "CREDENTIAL_INVALID" | "SESSION_EXPIRED" | "SESSION_INVALID" | "CANCELED" | "FAILED";
+type EmailProofErrorCode = "ADDRESS_INVALID" | "HOLDER_INVALID" | "CODE_INVALID" | "RATE_LIMITED" | "ISSUER_UNAVAILABLE" | "NETWORK" | "PROFILE_UNAVAILABLE" | "CODE_REJECTED" | "CODE_ATTEMPTS_EXHAUSTED" | "SIGNATURE_REJECTED" | "CREDENTIAL_INVALID" | "SESSION_EXPIRED" | "SESSION_INVALID" | "CLIENT_CLOCK_SKEW" | "CANCELED" | "FAILED";
 /** Stable, redaction-safe error. The message never includes the code, verifier, or key material. */
 declare class EmailProofError extends Error {
     readonly name = "EmailProofError";
@@ -40,7 +42,8 @@ declare class EmailProofError extends Error {
     readonly code: EmailProofErrorCode;
     readonly retryAfterMs: number | undefined;
     readonly recoverable: boolean;
-    constructor(step: EmailProofStep, code: EmailProofErrorCode, retryAfterMs?: number, recoverable?: boolean);
+    /** `message` overrides the code's text for one refusal whose cause the shared text would misdescribe. It never carries request data. */
+    constructor(step: EmailProofStep, code: EmailProofErrorCode, retryAfterMs?: number, recoverable?: boolean, message?: string);
 }
 type HolderAlgorithm = "EdDSA" | "EIP191";
 /**
@@ -63,6 +66,14 @@ interface HolderSigner {
 declare function createEd25519HolderSigner(did: string, sign: (bytes: Uint8Array) => Promise<Uint8Array>): HolderSigner;
 /** Options shared by the public steps. Issuer keys are never caller-supplied. */
 interface EmailProofOptions {
+    /**
+     * Per-call opt-in for the held profile `tinycloud.email-held/v1`. Only the literal `true` counts, it enables the held
+     * profile for this call alone (never stored in a pending, never read from the environment), and it is ignored for any other
+     * profile. Without it a held request is refused PROFILE_UNAVAILABLE before any network call. Nothing else can be supplied with
+     * it: the origin, issuer key and descriptor digest are compiled pins. The default 60 s step signal spans the wallet prompt in
+     * `completeEmailProof` for an account holder: pass a `signal` bounded by the request `expiresAt` if the user may take longer.
+     */
+    readonly allowHeldProfile?: true;
     readonly fetch?: typeof fetch;
     readonly signal?: AbortSignal;
     readonly now?: () => Date;
@@ -90,6 +101,8 @@ interface EmailProofPending {
     readonly openerOrigin: string;
     readonly createdAt: string;
     readonly expiresAt: string;
+    /** Held only: `expiresAt` of the create response (the witness's own deadline). The signed binding must carry it. */
+    readonly serverExpiresAt?: string;
 }
 /** Holds pending requests keyed by requestId. Implementations must never return an expired request from `findLive`. */
 interface EmailProofPendingStore {
@@ -104,13 +117,18 @@ interface EmailProofPendingStore {
 declare function createMemoryEmailProofPendingStore(): EmailProofPendingStore;
 interface EmailProofResult {
     readonly envelope: IssuedCredentialEnvelope;
-    readonly verified: VerifiedCredential;
+    /** The ticket verifier's result, or for the held profile (`envelope.profile.id`) the held verifier's. */
+    readonly verified: VerifiedCredential | VerifiedHeldEmailCredential;
     readonly credentialId: string;
     readonly issuedAt: string;
     readonly expiresAt: string;
     /** The descriptor the verifier checked against. Stored alongside the credential for offline re-verification. */
     readonly descriptor: CredentialFlowDescriptor;
 }
+/** True for a ticket (did:key) result, whose `verified` is the ticket verifier's output. The held profile's result carries the held verifier's. */
+declare function isTicketEmailProofResult(result: EmailProofResult): result is EmailProofResult & {
+    readonly verified: VerifiedCredential;
+};
 interface EmailProofAcquireInput extends EmailProofRequestInput {
     /** Supplies the 8-digit code. Omit to only request one; the pending request is returned for a later call. */
     readonly getCode?: (context: {
@@ -174,4 +192,4 @@ type StoredEmailProofInput = {
  */
 declare function verifyStoredEmailProof(input: StoredEmailProofInput): Promise<VerifiedCredential>;
 
-export { DEFAULT_EMAIL_PROOF_PROFILE as D, EMAIL_PROOF_CREDENTIAL_TYPE as E, type HolderAlgorithm as H, type StoredEmailProofInput as S, EMAIL_PROOF_PENDING_MAX_MS as a, type EmailProofAcquireInput as b, type EmailProofAcquisition as c, EmailProofError as d, type EmailProofErrorCode as e, type EmailProofOptions as f, type EmailProofPending as g, type EmailProofPendingStore as h, type EmailProofProfileId as i, type EmailProofRequestInput as j, type EmailProofResult as k, type EmailProofStep as l, type HolderSigner as m, type StoredEmailProofRecord as n, acquireEmailProof as o, completeEmailProof as p, createEd25519HolderSigner as q, createMemoryEmailProofPendingStore as r, emailProofRequirement as s, requestEmailProofCode as t, verifyStoredEmailProof as v };
+export { DEFAULT_EMAIL_PROOF_PROFILE as D, type EmailProofPendingStore as E, type HolderAlgorithm as H, type StoredEmailProofInput as S, type EmailProofPending as a, EMAIL_PROOF_CREDENTIAL_TYPE as b, EMAIL_PROOF_PENDING_MAX_MS as c, type EmailProofAcquireInput as d, type EmailProofAcquisition as e, EmailProofError as f, type EmailProofErrorCode as g, type EmailProofOptions as h, type EmailProofProfileId as i, type EmailProofRequestInput as j, type EmailProofResult as k, type EmailProofStep as l, type HolderSigner as m, type StoredEmailProofRecord as n, acquireEmailProof as o, completeEmailProof as p, createEd25519HolderSigner as q, createMemoryEmailProofPendingStore as r, emailProofRequirement as s, isTicketEmailProofResult as t, requestEmailProofCode as u, verifyStoredEmailProof as v };