@tinycloud/node-sdk 3.8.1-beta.2 → 3.9.0-beta.4

package/dist/{email-proof-GXXQhIff.d.cts → email-proof-BaOqVlB-.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";
@@ -6,7 +7,7 @@ declare const EMAIL_PROOF_CREDENTIAL_TYPE: {
 };
 /** A pending request is never trusted beyond this window, measured from creation. */
 declare const EMAIL_PROOF_PENDING_MAX_MS: number;
-type EmailProofProfileId = "tinycloud.email-proof/v1";
+type EmailProofProfileId = "tinycloud.email-proof/v1" | "tinycloud.email-held/v1";
 declare const DEFAULT_EMAIL_PROOF_PROFILE: EmailProofProfileId;
 /** Which part of the two-step flow failed. */
 type EmailProofStep = "request" | "code" | "credential" | "session";
@@ -29,10 +30,11 @@ type EmailProofStep = "request" | "code" | "credential" | "session";
  * | 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";
@@ -44,10 +46,11 @@ declare class EmailProofError extends Error {
 }
 type HolderAlgorithm = "EdDSA" | "EIP191";
 /**
- * Holder key adapter. `sign` MUST return a raw signature over exactly the bytes it
- * is given: the signer does no hashing, prefixing, or domain separation. `kid` names
- * the key the witness verifies against. `completeEmailProof` rejects with
+ * Holder key adapter. `kid` names the key the witness verifies against. `completeEmailProof` rejects with
  * SESSION_INVALID unless `did === pending.holderDid`.
+ * `sign` MUST return a raw signature over exactly the bytes it is given. For `EdDSA` the signer applies no
+ * prefix. For `EIP191` the adapter performs `personal_sign` over those bytes, and the wallet applies the
+ * `\x19Ethereum Signed Message:\n<len>` prefix. The prefix is applied in that one place and nowhere else.
  */
 interface HolderSigner {
     readonly did: string;
@@ -62,6 +65,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;
@@ -89,6 +100,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 {
@@ -103,13 +116,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: {
@@ -173,4 +191,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-GXXQhIff.d.ts → email-proof-BaOqVlB-.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";
@@ -6,7 +7,7 @@ declare const EMAIL_PROOF_CREDENTIAL_TYPE: {
 };
 /** A pending request is never trusted beyond this window, measured from creation. */
 declare const EMAIL_PROOF_PENDING_MAX_MS: number;
-type EmailProofProfileId = "tinycloud.email-proof/v1";
+type EmailProofProfileId = "tinycloud.email-proof/v1" | "tinycloud.email-held/v1";
 declare const DEFAULT_EMAIL_PROOF_PROFILE: EmailProofProfileId;
 /** Which part of the two-step flow failed. */
 type EmailProofStep = "request" | "code" | "credential" | "session";
@@ -29,10 +30,11 @@ type EmailProofStep = "request" | "code" | "credential" | "session";
  * | 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";
@@ -44,10 +46,11 @@ declare class EmailProofError extends Error {
 }
 type HolderAlgorithm = "EdDSA" | "EIP191";
 /**
- * Holder key adapter. `sign` MUST return a raw signature over exactly the bytes it
- * is given: the signer does no hashing, prefixing, or domain separation. `kid` names
- * the key the witness verifies against. `completeEmailProof` rejects with
+ * Holder key adapter. `kid` names the key the witness verifies against. `completeEmailProof` rejects with
  * SESSION_INVALID unless `did === pending.holderDid`.
+ * `sign` MUST return a raw signature over exactly the bytes it is given. For `EdDSA` the signer applies no
+ * prefix. For `EIP191` the adapter performs `personal_sign` over those bytes, and the wallet applies the
+ * `\x19Ethereum Signed Message:\n<len>` prefix. The prefix is applied in that one place and nowhere else.
  */
 interface HolderSigner {
     readonly did: string;
@@ -62,6 +65,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;
@@ -89,6 +100,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 {
@@ -103,13 +116,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: {
@@ -173,4 +191,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 };