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

package/dist/held-credentials/index.d.cts

@@ -5,6 +5,25 @@ declare class HeldCredentialError extends Error {
     constructor(code: HeldCredentialErrorCode, message: string);
 }
 
+interface PkhDid {
+    chainId: string;
+    /** Lowercase `0x` + 40 hex. */
+    address: string;
+}
+/** EIP-55 checksummed form of a `0x` + 40 hex address. */
+declare function toChecksumAddress(address: string): string;
+/** Parses `did:pkh:eip155:<chainId>:<address>`; null for anything else (no byte fallback). */
+declare function parsePkhDid(did: unknown): PkhDid | null;
+/** Principal equality: the exact eip155 chain id and the same address bytes. Never compares strings. */
+declare function pkhPrincipalsEqual(a: unknown, b: unknown): boolean;
+/**
+ * The one key billing, Exo and credentials.org use for a verified subject: the lowercase 20-byte
+ * address. It is chain-independent because v1 accepts only externally owned accounts (their control
+ * does not depend on the chain). Accepting contract wallets or other chains would require adding
+ * the chain here.
+ */
+declare function registryKey(subject: string): string;
+
 type Json = null | boolean | number | string | Json[] | {
     [key: string]: Json;
 };
@@ -96,6 +115,59 @@ interface IssuerSetOptions {
 /** Validates a whole issuer set. Any violation makes the whole set invalid. */
 declare function parseIssuerSet(raw: unknown, options: IssuerSetOptions): IssuerSet;
 
+interface AcceptedIssuer {
+    issuerDid: string;
+    kid?: string;
+}
+interface AcceptedProfile {
+    profile: string;
+    profileVersion: number;
+}
+interface VerifiedHeldCredential {
+    issuer: string;
+    subject: string;
+    /** Lowercase 20-byte address; equals `registryKey(subject)`. */
+    subjectAddress: string;
+    expiresAt: Date;
+    credentialId: string;
+    profile: string;
+    profileVersion: number;
+    vct: string;
+    claims: Record<string, Json>;
+}
+/** Base64url of SHA-256 over the ASCII bytes of the whole SD-JWT text (the sd_hash the SIWE resource binds). */
+declare function sdHash(sdJwt: string): string;
+/** `verifyHeldEmailCredential` output: the shared verified shape plus the signed issuance time (`iat`). The presentation verifier's output has no `issuedAt`. */
+interface VerifiedHeldEmailCredential extends VerifiedHeldCredential {
+    issuedAt: Date;
+}
+interface HeldEmailCredentialOptions {
+    /** Explicit clock. The verifier never reads one. */
+    now: Date;
+    issuerSet: IssuerSet;
+    /** From the owner-signed policy or the caller's allow-list. Empty is refused. */
+    acceptedIssuers: readonly AcceptedIssuer[];
+    /** Issuer methods the caller enables, e.g. ["web"]. */
+    didMethods: {
+        issuer: readonly string[];
+    };
+    /** The authenticated owner (`did:pkh:eip155:...`). The credential subject must be principal-equal to it. */
+    owner: string;
+}
+/**
+ * Verifies a held email credential on its own. No presentation proof and no nonce: the caller must
+ * already hold the SD-JWT and have authenticated `owner`. Refuses an owner mismatch with the same
+ * code as the presentation path. Synchronous; the email row is fixed.
+ * The code `nonce-account-mismatch` is kept for parity with the presentation path. This path spends no nonce.
+ */
+declare function verifyHeldEmailCredential(sdJwt: unknown, options: HeldEmailCredentialOptions): VerifiedHeldEmailCredential;
+/**
+ * Structural selective disclosure: keeps only the disclosures named in `names`, in their original
+ * order, and drops any key-binding suffix. It does not verify anything. Verify the full SD-JWT
+ * first; this function only re-shapes a verified presentation.
+ */
+declare function selectDisclosures(sdJwt: string, names: readonly string[]): string;
+
 /**
  * Single use is a property of the store. `consume` is one atomic compare-and-delete and the only
  * nonce operation a verifier performs: it deletes the entry only where the audience, the nonce and
@@ -131,14 +203,6 @@ interface HeldPresentation {
         signature: string;
     };
 }
-interface AcceptedIssuer {
-    issuerDid: string;
-    kid?: string;
-}
-interface AcceptedProfile {
-    profile: string;
-    profileVersion: number;
-}
 interface VerifyHeldPresentationOptions {
     /** Explicit clock. The verifier never reads one. */
     now: Date;
@@ -162,18 +226,6 @@ interface VerifyHeldPresentationOptions {
     /** Defaults to the email row. */
     rows?: readonly ProfileRow[];
 }
-interface VerifiedHeldCredential {
-    issuer: string;
-    subject: string;
-    /** Lowercase 20-byte address; equals `registryKey(subject)`. */
-    subjectAddress: string;
-    expiresAt: Date;
-    credentialId: string;
-    profile: string;
-    profileVersion: number;
-    vct: string;
-    claims: Record<string, Json>;
-}
 /**
  * Verifies a held-credential presentation (spec §4.4). Fail closed: the first failed check throws a
  * HeldCredentialError. The caller-bound nonce is spent first, on any outcome. No payload claim is read before the issuer signature has verified.
@@ -185,25 +237,6 @@ declare const SD_HASH_RESOURCE_PREFIX = "urn:tinycloud:sd-hash:";
 /** An audience is a bare RFC 3986 authority: lowercase host[:port], no scheme, userinfo, path, or default port 443. */
 declare function assertValidAudience(audience: string): void;
 
-interface PkhDid {
-    chainId: string;
-    /** Lowercase `0x` + 40 hex. */
-    address: string;
-}
-/** EIP-55 checksummed form of a `0x` + 40 hex address. */
-declare function toChecksumAddress(address: string): string;
-/** Parses `did:pkh:eip155:<chainId>:<address>`; null for anything else (no byte fallback). */
-declare function parsePkhDid(did: unknown): PkhDid | null;
-/** Principal equality: the exact eip155 chain id and the same address bytes. Never compares strings. */
-declare function pkhPrincipalsEqual(a: unknown, b: unknown): boolean;
-/**
- * The one key billing, Exo and credentials.org use for a verified subject: the lowercase 20-byte
- * address. It is chain-independent because v1 accepts only externally owned accounts (their control
- * does not depend on the chain). Accepting contract wallets or other chains would require adding
- * the chain here.
- */
-declare function registryKey(subject: string): string;
-
 /**
  * THE single shared email normalisation function (gap G14; the same rules as billing's
  * `src/email-normalise.ts`, TC-1439). The alias rules below are confirmed by Sam on 2026-10-19
@@ -221,4 +254,48 @@ declare function registryKey(subject: string): string;
  */
 declare function normaliseEmail(email: string): string | null;
 
-export { ACCOUNT_BINDING_DOMAIN, type AcceptedIssuer, type AcceptedProfile, DEFAULT_ROWS, EMAIL_HELD_ROW, HELD_EMAIL_TTL_SECONDS, HeldCredentialError, type HeldCredentialErrorCode, type HeldPresentation, ISSUER_SET_FORMAT, InMemoryNonceStore, type IssuerEntry, IssuerSet, type IssuerSetOptions, type NonceStore, ORG_MEMBERSHIP_FREE_ROW, ORG_MEMBERSHIP_ROW, ORG_MEMBERSHIP_ROWS, PRESENTATION_STATEMENT, type ProfileRow, SD_HASH_RESOURCE_PREFIX, type VerifiedHeldCredential, type VerifyHeldPresentationOptions, assertValidAudience, normaliseEmail, parseIssuerSet, parsePkhDid, pkhPrincipalsEqual, randomNonce, registryKey, toChecksumAddress, verifyHeldPresentation };
+/** Signs an EIP-191 `personal_sign` message. Returns `0x` + 130 hex (r, s, v) with low-S. Called once per presentation. */
+type HeldPresentationSigner = (message: string) => Promise<string>;
+interface HeldPresentationSiwe {
+    message: string;
+    signature: string;
+}
+interface BuildHeldPresentationSiweInput {
+    /** The verifier's audience: a bare host[:port] authority. It becomes the SIWE domain and the https origin. */
+    audience: string;
+    /** Nonce minted by the verifier for `audience`, bound to `account`. At least 22 base62 characters. */
+    nonce: string;
+    /** Base64url SHA-256 of the presented SD-JWT: `sdHash(selectDisclosures(...))`. */
+    sdHash: string;
+    /** The holder's `did:pkh:eip155:1:<address>`. */
+    account: string;
+    /** Whole seconds only, as RFC 3339 `Z`. Sub-second precision is refused, not truncated. */
+    issuedAt: Date;
+    /** Whole seconds only, as RFC 3339 `Z`. Must be after `issuedAt`. */
+    expirationTime?: Date;
+    /** Produces the signature. Each call builds a fresh message; nothing is cached. */
+    sign: HeldPresentationSigner;
+}
+interface CheckReturnedPresentationOptions {
+    /** Explicit clock for the SIWE expiry and not-before windows. */
+    now: Date;
+    /** The verifier's audience. The SIWE domain and https origin must match it. */
+    audience: string;
+    /** The holder's `did:pkh:eip155:1:<address>`. The SIWE address must be principal-equal to it. */
+    account: string;
+}
+/**
+ * Builds the EIP-4361 message for a held presentation in the layout `parseStrictSiwe` accepts, and
+ * signs it with `sign`. The signature must recover to `account`. The verifier, not this builder,
+ * decides whether the presentation is accepted.
+ */
+declare function buildHeldPresentationSiwe(input: BuildHeldPresentationSiweInput): Promise<HeldPresentationSiwe>;
+/**
+ * Client-side check of a presentation before it is sent on. It is not a verifier: it does not look
+ * up issuers, spend a nonce, or check the credential signature. `verifyHeldPresentation` decides acceptance.
+ * It refuses a high-S signature, as `buildHeldPresentationSiwe` does. That is stricter than the Rust verifier,
+ * which accepts high-S signatures: a presentation this check refuses can still be one the verifier would accept.
+ */
+declare function checkReturnedPresentation(presentation: unknown, options: CheckReturnedPresentationOptions): HeldPresentation;
+
+export { ACCOUNT_BINDING_DOMAIN, type AcceptedIssuer, type AcceptedProfile, type BuildHeldPresentationSiweInput, type CheckReturnedPresentationOptions, DEFAULT_ROWS, EMAIL_HELD_ROW, HELD_EMAIL_TTL_SECONDS, HeldCredentialError, type HeldCredentialErrorCode, type HeldEmailCredentialOptions, type HeldPresentation, type HeldPresentationSigner, type HeldPresentationSiwe, ISSUER_SET_FORMAT, InMemoryNonceStore, type IssuerEntry, IssuerSet, type IssuerSetOptions, type NonceStore, ORG_MEMBERSHIP_FREE_ROW, ORG_MEMBERSHIP_ROW, ORG_MEMBERSHIP_ROWS, PRESENTATION_STATEMENT, type ProfileRow, SD_HASH_RESOURCE_PREFIX, type VerifiedHeldCredential, type VerifiedHeldEmailCredential, type VerifyHeldPresentationOptions, assertValidAudience, buildHeldPresentationSiwe, checkReturnedPresentation, normaliseEmail, parseIssuerSet, parsePkhDid, pkhPrincipalsEqual, randomNonce, registryKey, sdHash, selectDisclosures, toChecksumAddress, verifyHeldEmailCredential, verifyHeldPresentation };

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

@@ -5,6 +5,25 @@ declare class HeldCredentialError extends Error {
     constructor(code: HeldCredentialErrorCode, message: string);
 }
 
+interface PkhDid {
+    chainId: string;
+    /** Lowercase `0x` + 40 hex. */
+    address: string;
+}
+/** EIP-55 checksummed form of a `0x` + 40 hex address. */
+declare function toChecksumAddress(address: string): string;
+/** Parses `did:pkh:eip155:<chainId>:<address>`; null for anything else (no byte fallback). */
+declare function parsePkhDid(did: unknown): PkhDid | null;
+/** Principal equality: the exact eip155 chain id and the same address bytes. Never compares strings. */
+declare function pkhPrincipalsEqual(a: unknown, b: unknown): boolean;
+/**
+ * The one key billing, Exo and credentials.org use for a verified subject: the lowercase 20-byte
+ * address. It is chain-independent because v1 accepts only externally owned accounts (their control
+ * does not depend on the chain). Accepting contract wallets or other chains would require adding
+ * the chain here.
+ */
+declare function registryKey(subject: string): string;
+
 type Json = null | boolean | number | string | Json[] | {
     [key: string]: Json;
 };
@@ -96,6 +115,59 @@ interface IssuerSetOptions {
 /** Validates a whole issuer set. Any violation makes the whole set invalid. */
 declare function parseIssuerSet(raw: unknown, options: IssuerSetOptions): IssuerSet;
 
+interface AcceptedIssuer {
+    issuerDid: string;
+    kid?: string;
+}
+interface AcceptedProfile {
+    profile: string;
+    profileVersion: number;
+}
+interface VerifiedHeldCredential {
+    issuer: string;
+    subject: string;
+    /** Lowercase 20-byte address; equals `registryKey(subject)`. */
+    subjectAddress: string;
+    expiresAt: Date;
+    credentialId: string;
+    profile: string;
+    profileVersion: number;
+    vct: string;
+    claims: Record<string, Json>;
+}
+/** Base64url of SHA-256 over the ASCII bytes of the whole SD-JWT text (the sd_hash the SIWE resource binds). */
+declare function sdHash(sdJwt: string): string;
+/** `verifyHeldEmailCredential` output: the shared verified shape plus the signed issuance time (`iat`). The presentation verifier's output has no `issuedAt`. */
+interface VerifiedHeldEmailCredential extends VerifiedHeldCredential {
+    issuedAt: Date;
+}
+interface HeldEmailCredentialOptions {
+    /** Explicit clock. The verifier never reads one. */
+    now: Date;
+    issuerSet: IssuerSet;
+    /** From the owner-signed policy or the caller's allow-list. Empty is refused. */
+    acceptedIssuers: readonly AcceptedIssuer[];
+    /** Issuer methods the caller enables, e.g. ["web"]. */
+    didMethods: {
+        issuer: readonly string[];
+    };
+    /** The authenticated owner (`did:pkh:eip155:...`). The credential subject must be principal-equal to it. */
+    owner: string;
+}
+/**
+ * Verifies a held email credential on its own. No presentation proof and no nonce: the caller must
+ * already hold the SD-JWT and have authenticated `owner`. Refuses an owner mismatch with the same
+ * code as the presentation path. Synchronous; the email row is fixed.
+ * The code `nonce-account-mismatch` is kept for parity with the presentation path. This path spends no nonce.
+ */
+declare function verifyHeldEmailCredential(sdJwt: unknown, options: HeldEmailCredentialOptions): VerifiedHeldEmailCredential;
+/**
+ * Structural selective disclosure: keeps only the disclosures named in `names`, in their original
+ * order, and drops any key-binding suffix. It does not verify anything. Verify the full SD-JWT
+ * first; this function only re-shapes a verified presentation.
+ */
+declare function selectDisclosures(sdJwt: string, names: readonly string[]): string;
+
 /**
  * Single use is a property of the store. `consume` is one atomic compare-and-delete and the only
  * nonce operation a verifier performs: it deletes the entry only where the audience, the nonce and
@@ -131,14 +203,6 @@ interface HeldPresentation {
         signature: string;
     };
 }
-interface AcceptedIssuer {
-    issuerDid: string;
-    kid?: string;
-}
-interface AcceptedProfile {
-    profile: string;
-    profileVersion: number;
-}
 interface VerifyHeldPresentationOptions {
     /** Explicit clock. The verifier never reads one. */
     now: Date;
@@ -162,18 +226,6 @@ interface VerifyHeldPresentationOptions {
     /** Defaults to the email row. */
     rows?: readonly ProfileRow[];
 }
-interface VerifiedHeldCredential {
-    issuer: string;
-    subject: string;
-    /** Lowercase 20-byte address; equals `registryKey(subject)`. */
-    subjectAddress: string;
-    expiresAt: Date;
-    credentialId: string;
-    profile: string;
-    profileVersion: number;
-    vct: string;
-    claims: Record<string, Json>;
-}
 /**
  * Verifies a held-credential presentation (spec §4.4). Fail closed: the first failed check throws a
  * HeldCredentialError. The caller-bound nonce is spent first, on any outcome. No payload claim is read before the issuer signature has verified.
@@ -185,25 +237,6 @@ declare const SD_HASH_RESOURCE_PREFIX = "urn:tinycloud:sd-hash:";
 /** An audience is a bare RFC 3986 authority: lowercase host[:port], no scheme, userinfo, path, or default port 443. */
 declare function assertValidAudience(audience: string): void;
 
-interface PkhDid {
-    chainId: string;
-    /** Lowercase `0x` + 40 hex. */
-    address: string;
-}
-/** EIP-55 checksummed form of a `0x` + 40 hex address. */
-declare function toChecksumAddress(address: string): string;
-/** Parses `did:pkh:eip155:<chainId>:<address>`; null for anything else (no byte fallback). */
-declare function parsePkhDid(did: unknown): PkhDid | null;
-/** Principal equality: the exact eip155 chain id and the same address bytes. Never compares strings. */
-declare function pkhPrincipalsEqual(a: unknown, b: unknown): boolean;
-/**
- * The one key billing, Exo and credentials.org use for a verified subject: the lowercase 20-byte
- * address. It is chain-independent because v1 accepts only externally owned accounts (their control
- * does not depend on the chain). Accepting contract wallets or other chains would require adding
- * the chain here.
- */
-declare function registryKey(subject: string): string;
-
 /**
  * THE single shared email normalisation function (gap G14; the same rules as billing's
  * `src/email-normalise.ts`, TC-1439). The alias rules below are confirmed by Sam on 2026-10-19
@@ -221,4 +254,48 @@ declare function registryKey(subject: string): string;
  */
 declare function normaliseEmail(email: string): string | null;
 
-export { ACCOUNT_BINDING_DOMAIN, type AcceptedIssuer, type AcceptedProfile, DEFAULT_ROWS, EMAIL_HELD_ROW, HELD_EMAIL_TTL_SECONDS, HeldCredentialError, type HeldCredentialErrorCode, type HeldPresentation, ISSUER_SET_FORMAT, InMemoryNonceStore, type IssuerEntry, IssuerSet, type IssuerSetOptions, type NonceStore, ORG_MEMBERSHIP_FREE_ROW, ORG_MEMBERSHIP_ROW, ORG_MEMBERSHIP_ROWS, PRESENTATION_STATEMENT, type ProfileRow, SD_HASH_RESOURCE_PREFIX, type VerifiedHeldCredential, type VerifyHeldPresentationOptions, assertValidAudience, normaliseEmail, parseIssuerSet, parsePkhDid, pkhPrincipalsEqual, randomNonce, registryKey, toChecksumAddress, verifyHeldPresentation };
+/** Signs an EIP-191 `personal_sign` message. Returns `0x` + 130 hex (r, s, v) with low-S. Called once per presentation. */
+type HeldPresentationSigner = (message: string) => Promise<string>;
+interface HeldPresentationSiwe {
+    message: string;
+    signature: string;
+}
+interface BuildHeldPresentationSiweInput {
+    /** The verifier's audience: a bare host[:port] authority. It becomes the SIWE domain and the https origin. */
+    audience: string;
+    /** Nonce minted by the verifier for `audience`, bound to `account`. At least 22 base62 characters. */
+    nonce: string;
+    /** Base64url SHA-256 of the presented SD-JWT: `sdHash(selectDisclosures(...))`. */
+    sdHash: string;
+    /** The holder's `did:pkh:eip155:1:<address>`. */
+    account: string;
+    /** Whole seconds only, as RFC 3339 `Z`. Sub-second precision is refused, not truncated. */
+    issuedAt: Date;
+    /** Whole seconds only, as RFC 3339 `Z`. Must be after `issuedAt`. */
+    expirationTime?: Date;
+    /** Produces the signature. Each call builds a fresh message; nothing is cached. */
+    sign: HeldPresentationSigner;
+}
+interface CheckReturnedPresentationOptions {
+    /** Explicit clock for the SIWE expiry and not-before windows. */
+    now: Date;
+    /** The verifier's audience. The SIWE domain and https origin must match it. */
+    audience: string;
+    /** The holder's `did:pkh:eip155:1:<address>`. The SIWE address must be principal-equal to it. */
+    account: string;
+}
+/**
+ * Builds the EIP-4361 message for a held presentation in the layout `parseStrictSiwe` accepts, and
+ * signs it with `sign`. The signature must recover to `account`. The verifier, not this builder,
+ * decides whether the presentation is accepted.
+ */
+declare function buildHeldPresentationSiwe(input: BuildHeldPresentationSiweInput): Promise<HeldPresentationSiwe>;
+/**
+ * Client-side check of a presentation before it is sent on. It is not a verifier: it does not look
+ * up issuers, spend a nonce, or check the credential signature. `verifyHeldPresentation` decides acceptance.
+ * It refuses a high-S signature, as `buildHeldPresentationSiwe` does. That is stricter than the Rust verifier,
+ * which accepts high-S signatures: a presentation this check refuses can still be one the verifier would accept.
+ */
+declare function checkReturnedPresentation(presentation: unknown, options: CheckReturnedPresentationOptions): HeldPresentation;
+
+export { ACCOUNT_BINDING_DOMAIN, type AcceptedIssuer, type AcceptedProfile, type BuildHeldPresentationSiweInput, type CheckReturnedPresentationOptions, DEFAULT_ROWS, EMAIL_HELD_ROW, HELD_EMAIL_TTL_SECONDS, HeldCredentialError, type HeldCredentialErrorCode, type HeldEmailCredentialOptions, type HeldPresentation, type HeldPresentationSigner, type HeldPresentationSiwe, ISSUER_SET_FORMAT, InMemoryNonceStore, type IssuerEntry, IssuerSet, type IssuerSetOptions, type NonceStore, ORG_MEMBERSHIP_FREE_ROW, ORG_MEMBERSHIP_ROW, ORG_MEMBERSHIP_ROWS, PRESENTATION_STATEMENT, type ProfileRow, SD_HASH_RESOURCE_PREFIX, type VerifiedHeldCredential, type VerifiedHeldEmailCredential, type VerifyHeldPresentationOptions, assertValidAudience, buildHeldPresentationSiwe, checkReturnedPresentation, normaliseEmail, parseIssuerSet, parsePkhDid, pkhPrincipalsEqual, randomNonce, registryKey, sdHash, selectDisclosures, toChecksumAddress, verifyHeldEmailCredential, verifyHeldPresentation };