@coordination-network/user-app-core 0.0.1

package/types/index.d.ts

@@ -0,0 +1,238 @@
+import { Hex } from '@coordination-network/identity';
+import { DeviceSigner } from '@coordination-network/credential';
+import { Store, ProofGenerator, CredentialInfo } from '@coordination-network/wallet';
+import { Caller, SecurityLevel, Hex32, Hex66, Hex65, LinkOp, LinkHandlers, DecodedLinkRequest, LinkErrorCode, LinkError } from '@coordination-network/user-app-link';
+
+/**
+ * The holder P-256 device key. Extends `DeviceSigner` (rather than replacing it) so a `DeviceKey`
+ * is accepted as-is anywhere a `DeviceSigner` is expected — `Wallet`, `buildZkPresentationInputs`,
+ * `deriveDeviceKeyCommitment`.
+ */
+interface DeviceKey extends DeviceSigner {
+    /** X coordinate of hwPriv · peerPublicKey, 32 raw bytes. Feeds `deriveEddsaKeypair`. */
+    ecdh(peerPublicKey: Uint8Array): Promise<Uint8Array>;
+    getSecurityLevel(): Promise<SecurityLevel>;
+}
+/** A minimal HTTP JSON port: no DOM or RN fetch types needed, and a test fake is three lines. */
+interface HttpJsonResponse {
+    status: number;
+    body: unknown;
+}
+interface HttpClient {
+    getJson(url: string): Promise<HttpJsonResponse>;
+    postJson(url: string, body: unknown): Promise<HttpJsonResponse>;
+}
+/** One human-readable line of a consent screen, e.g. `{ label: "Programme", value: "demo-programme" }`. */
+interface ConsentDetail {
+    label: string;
+    value: string;
+    /** Set false for a value whose full text is the point and must never hide behind a tap - the callback. */
+    truncate?: boolean;
+}
+/** The programme and country a consent sentence names, on the two ops that scope one. */
+interface ConsentScope {
+    programme: string;
+    country: string;
+}
+interface ConsentSummaryBase {
+    caller: Caller;
+    /** The technical rows the consent sheet folds away, in the order it lists them. */
+    details: ConsentDetail[];
+}
+/**
+ * What a request amounts to, in values rather than sentences: the wallet writes every line a
+ * person reads, so that it can name the caller mid-sentence in the caller's own colour. Keyed by
+ * `op` so a screen that switches on it gets `scope` typed rather than optional.
+ */
+type ConsentSummary = (ConsentSummaryBase & {
+    op: "registration.sign";
+}) | (ConsentSummaryBase & {
+    op: "credential.issue";
+    scope: ConsentScope;
+}) | (ConsentSummaryBase & {
+    op: "presentation.create";
+    scope: ConsentScope;
+});
+/** The single consent gate: shown once per deep link, before dispatch. */
+type UserConsentPrompt = (summary: ConsentSummary) => Promise<boolean>;
+interface PresentationReviewBase {
+    verifier: string;
+    programme: string;
+    country: string;
+    issuerNetworkId: Hex32;
+}
+/**
+ * What a verifier would learn. `proof` is what the built proof reveals, which is no longer the
+ * issuer: a presentation proves membership of the whole approved set and carries one network-wide
+ * revocation root, so nothing in it singles an issuer out. `issuerNetworkId` is still here because
+ * the person is shown which of their own credentials answered. `revoked` is the refusal itself:
+ * telling a verifier that the person holds a revoked credential says something about them that no
+ * proof would have, so it is theirs to allow.
+ */
+type PresentationReview = (PresentationReviewBase & {
+    kind: "proof";
+}) | (PresentationReviewBase & {
+    kind: "revoked";
+});
+/**
+ * The second gate, on `presentation.create` only: nothing has left the phone yet, so the person
+ * can be shown what would. `false` refuses with `CONSENT_DENIED`.
+ */
+type PresentationReviewPrompt = (summary: PresentationReview) => Promise<boolean>;
+/**
+ * Whether a held credential has been revoked, from the one registry the whole network writes to.
+ * `null` is "nobody to ask": no stack is configured, or it could not be reached. The caller then
+ * says it has not checked, rather than calling a credential valid on the strength of its dates.
+ */
+interface RevocationAuthority {
+    isRevoked(commitment: bigint): Promise<boolean | null>;
+}
+interface UserAppPorts {
+    store: Store;
+    deviceKey: DeviceKey;
+    proofGenerator: ProofGenerator;
+    http: HttpClient;
+    consent: UserConsentPrompt;
+    review: PresentationReviewPrompt;
+    /** Absent leaves every held credential's revocation unchecked; see {@link RevocationAuthority}. */
+    revocations?: RevocationAuthority;
+    /** Named steps inside a long handler, for a screen that shows what the wallet is doing. */
+    progress: (op: LinkOp, step: string) => void;
+    now?: () => number;
+}
+/** What the app's own Identity screen shows; assembled from the device secret, never from a link. */
+interface PublicIdentity {
+    networkId: Hex32;
+    metaStealthAddress: Hex66;
+    accountPublicKey: Hex65;
+    securityLevel: SecurityLevel;
+}
+/**
+ * What a held credential's state can honestly be called here. The validity window is signed into
+ * the credential body, so it is answerable offline. Revocation takes an authority, and there is now
+ * exactly one for the whole network — asking it names no issuer, which is what makes this listing
+ * able to say "revoked" at all. Issuer approval stays out: an approved-issuer set is still each
+ * member's own, so this screen has no one to ask and reports nothing.
+ *
+ * `unchecked` is a credential inside its window whose revocation could not be established. It is
+ * deliberately not folded into `valid`: the difference between "the network says this is live" and
+ * "nobody could be asked" is the whole point of showing a status.
+ */
+type HeldCredentialStatus = "valid" | "revoked" | "not-yet-valid" | "expired" | "unchecked";
+interface HeldCredential {
+    id: string;
+    /** See {@link HeldCredentialStatus}: the window and revocation, never issuer approval. */
+    status: HeldCredentialStatus;
+    /** The three fields the credential body cannot give back, kept in the issuer index at issuance. */
+    issuerNetworkId: Hex32;
+    programme: string;
+    issuedAt: number;
+    /** A one-way hash of {@link programme}, as signed into the credential. */
+    programmeHash: string;
+    /** Unlike `programmeHash`, exactly invertible: `countryCode` just packs three ASCII bytes. */
+    country: string;
+    notBefore: number;
+    expiresAt: number;
+}
+/**
+ * The two keys an app needs to scan ERC-5564 announcements for itself, where there is no indexer.
+ * `viewingPrivateKey` is a private key: it detects incoming payments but cannot spend, and it is
+ * deliberately the narrowest thing that does the job — far less than the device secret every other
+ * key derives from.
+ */
+interface StealthScanKeys {
+    spendingPublicKey: Hex;
+    viewingPrivateKey: Hex;
+}
+interface UserAppService {
+    readonly handlers: LinkHandlers;
+    consent(request: DecodedLinkRequest): Promise<boolean>;
+    isOnboarded(): Promise<boolean>;
+    createIdentity(): Promise<PublicIdentity>;
+    readIdentity(): Promise<PublicIdentity>;
+    listCredentials(): Promise<HeldCredential[]>;
+    /** See {@link StealthScanKeys}. Throws if no identity has been created. */
+    readStealthScanKeys(): Promise<StealthScanKeys>;
+    erase(): Promise<void>;
+}
+
+declare function createUserAppService(ports: UserAppPorts): UserAppService;
+
+/**
+ * Preserves the original message on the thrown `LinkError`. `chainStateCode` names the side whose
+ * lists were being read: during issuance that is the issuer, not a verifier.
+ *
+ * Takes `unknown` rather than `WalletError` because the wallet's sync methods are not total over
+ * `WalletError`: they parse each stored credential and write each record back, so a corrupt record
+ * or a failing device store throws something else entirely. Indexing the table with that error's
+ * absent `code` would have produced a `LinkError` with no code at all.
+ */
+declare function mapWalletError(error: unknown, chainStateCode?: LinkErrorCode): LinkError;
+
+interface CredentialSelectionRequest {
+    programme: string;
+    country: string;
+}
+/**
+ * `presentation.create` carries no credential id, so this narrows by what the credential body
+ * says: the requested programme and country. Status is deliberately not a filter — each candidate
+ * is then synced against its own issuer's snapshot, and a caller that finds none valid still
+ * needs to know whether it held a revoked one.
+ */
+declare function matchingCredentials<T extends CredentialInfo>(credentials: T[], request: CredentialSelectionRequest): T[];
+/** Of the credentials still usable, the one that stays usable longest, tie-broken by id for determinism. */
+declare function latestExpiring<T extends CredentialInfo>(credentials: T[]): T | null;
+
+/**
+ * `createRequestHandler` calls this after confirming `request.op` is a known op and validating
+ * `params` against its schema, so the casts below are re-attaching types the caller already
+ * proved, not asserting past them — an exhaustive switch covers every case with no defensive
+ * default branch needed. Every value here ends up behind the sheet's "Technical details" toggle;
+ * the sentence above it is the app's, not this package's.
+ */
+declare function buildConsentSummary(request: DecodedLinkRequest): ConsentSummary;
+
+/**
+ * This package holds exactly one identity, so unlike `Wallet`'s `key:`-prefixed store (built for
+ * several imported keys) the device secret lives under one fixed key.
+ */
+declare const DEVICE_SECRET_KEY = "user-app-core:device-secret";
+
+/**
+ * The steps `credential.issue` reports, in the order it reports them. Named here rather than
+ * spelled out twice, so the screen that groups the six into the three a person approved cannot
+ * drift from the handler reporting them.
+ */
+declare const CREDENTIAL_ISSUE_STEPS: {
+    readonly held: "Checking what you hold";
+    readonly lists: "Checking the lists";
+    readonly challenge: "Getting a challenge";
+    readonly binding: "Binding to this phone";
+    readonly signing: "Asking the issuer to sign";
+    readonly storing: "Saving to your wallet";
+};
+
+/**
+ * One entry per issuer the wallet holds a credential from. It carries what the credential body
+ * cannot give back — the plaintext programme and the issuer — so a listing can name both.
+ */
+interface IssuerIndexEntry {
+    credentialId: string;
+    /** The Baby Jubjub key that signed the credential, as decimal field elements. */
+    issuerPublicKey: [string, string];
+    /** Where the issuer published its own approved-issuer set at issuance. Nothing reads it yet:
+     *  a presentation reads the verifier's, which is why a hostile verifier can still probe for the
+     *  issuer by serving a subset. Recorded so that check can be anchored here instead. */
+    issuersUrl: string;
+    programme: string;
+    country: string;
+    issuedAt: number;
+}
+declare function readIssuerEntry(store: Store, issuerNetworkId: Hex32, scope: ConsentScope): Promise<IssuerIndexEntry | null>;
+/** Every entry the wallet holds, for the joins that start from a credential rather than an issuer. */
+declare function listIssuerEntries(store: Store): Promise<(IssuerIndexEntry & {
+    issuerNetworkId: Hex32;
+})[]>;
+
+export { CREDENTIAL_ISSUE_STEPS, DEVICE_SECRET_KEY, buildConsentSummary, createUserAppService, latestExpiring, listIssuerEntries, mapWalletError, matchingCredentials, readIssuerEntry };
+export type { ConsentDetail, ConsentScope, ConsentSummary, CredentialSelectionRequest, DeviceKey, HeldCredential, HeldCredentialStatus, HttpClient, HttpJsonResponse, IssuerIndexEntry, PresentationReview, PresentationReviewPrompt, PublicIdentity, RevocationAuthority, StealthScanKeys, UserAppPorts, UserAppService, UserConsentPrompt };