@receiz/sdk 93.1.0 → 94.0.0

package/dist/index.js

@@ -1,7 +1,93 @@
-export const RECEIZ_SDK_VERSION = "93.1.0";
+import { buildReceizIdContinueRequest, createReceizIdIdentity, projectReceizIdentityAccount, readReceizIdentityArtifact, signReceizIdentityLoginProof, verifyReceizIdentityLoginProof, } from "./identity.js";
+export * from "./identity.js";
+export const RECEIZ_SDK_VERSION = "94.0.0";
 export const RECEIZ_DEFAULT_BASE_URL = "https://receiz.com";
 export const RECEIZ_WEBHOOK_SIGNATURE_HEADER = "x-receiz-signature";
 export const RECEIZ_WEBHOOK_TIMESTAMP_HEADER = "x-receiz-timestamp";
+export const RECEIZ_ASSET_MANIFEST_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://receiz.com/standards/receiz.asset-manifest.schema.v1.json",
+    title: "Receiz Asset Manifest",
+    type: "object",
+    additionalProperties: true,
+    required: ["schema", "assetId", "assetType", "proof", "links"],
+    properties: {
+        schema: { const: "receiz.asset_manifest.v1" },
+        assetId: { type: "string", minLength: 1 },
+        assetType: {
+            enum: ["proof_object", "sports_card", "signal_card", "wallet_note", "market_certificate", "profile_original", "document"],
+        },
+        proof: {
+            type: "object",
+            required: ["kind"],
+            additionalProperties: true,
+            properties: {
+                kind: { type: "string", minLength: 1 },
+                verifyUrl: { type: "string" },
+                kaiPulseEternal: { type: ["number", "string"] },
+            },
+        },
+        owner: { type: ["object", "null"], additionalProperties: true },
+        media: { type: ["object", "null"], additionalProperties: true },
+        appends: { type: "array", items: { type: "object", additionalProperties: true } },
+        settlement: { type: ["object", "null"], additionalProperties: true },
+        links: { type: "object", additionalProperties: { type: "string" } },
+    },
+};
+export const RECEIZ_SPORTS_CARD_MANIFEST_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://receiz.com/standards/receiz.sports-card-manifest.schema.v1.json",
+    title: "Receiz Sports Arena Card Manifest",
+    type: "object",
+    additionalProperties: true,
+    required: ["schema", "sport", "collectibleId", "claimHash", "card", "ownership", "valueBasis", "links"],
+    properties: {
+        schema: { const: "receiz.sports_arena.card_manifest.v1" },
+        sport: { type: "string", minLength: 1 },
+        collectibleId: { type: "string", minLength: 1 },
+        claimHash: { type: "string", minLength: 1 },
+        card: { type: "object", additionalProperties: true },
+        ownership: { type: "object", additionalProperties: true },
+        valueBasis: { type: "object", additionalProperties: true },
+        appendSummary: { type: ["object", "null"], additionalProperties: true },
+        eventProofSummary: { type: ["object", "null"], additionalProperties: true },
+        links: { type: "object", additionalProperties: { type: "string" } },
+    },
+};
+export const RECEIZ_WEBHOOK_EVENT_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://receiz.com/standards/receiz.webhook-event.schema.v1.json",
+    title: "Receiz Webhook Event",
+    type: "object",
+    additionalProperties: true,
+    required: ["schema", "id", "type", "createdAt", "data"],
+    properties: {
+        schema: { const: "receiz.webhook_event.v1" },
+        id: { type: "string", minLength: 1 },
+        type: {
+            enum: [
+                "asset.created",
+                "asset.transferred",
+                "proof.appended",
+                "sports_card.scored",
+                "event_proof.created",
+                "wallet.ledger_entry",
+                "note.claimed",
+                "market.trade",
+                "profile.asset.visible_changed",
+            ],
+        },
+        createdAt: { type: "string", minLength: 1 },
+        data: { type: "object", additionalProperties: true },
+        actor: { type: ["object", "null"], additionalProperties: true },
+        signature: { type: ["object", "null"], additionalProperties: true },
+    },
+};
+export const RECEIZ_SCHEMAS = {
+    assetManifest: RECEIZ_ASSET_MANIFEST_SCHEMA,
+    sportsCardManifest: RECEIZ_SPORTS_CARD_MANIFEST_SCHEMA,
+    webhookEvent: RECEIZ_WEBHOOK_EVENT_SCHEMA,
+};
 export class ReceizHttpError extends Error {
     status;
     payload;
@@ -179,6 +265,13 @@ export class ReceizClient {
         downloadNote: (noteId) => this.delegated(`/api/connect/payments/notes/${encodePathSegment(noteId)}/download`),
     };
     identity = {
+        createReceizId: createReceizIdIdentity,
+        readArtifact: readReceizIdentityArtifact,
+        projectAccount: projectReceizIdentityAccount,
+        signLoginProof: signReceizIdentityLoginProof,
+        verifyLoginProof: verifyReceizIdentityLoginProof,
+        buildReceizIdContinueRequest,
+        continueReceizId: (identity, options = {}) => this.continueReceizId(identity, options),
         openIdConfiguration: () => this.request("/.well-known/openid-configuration"),
         oauthAuthorizationServerMetadata: () => this.request("/.well-known/oauth-authorization-server"),
         jwks: () => this.request("/api/oidc/jwks"),
@@ -227,6 +320,16 @@ export class ReceizClient {
         isAsset: isReceizAssetManifest,
         isSportsCard: isReceizSportsCardManifest,
         isWebhookEvent: isReceizWebhookEvent,
+        projectAsset: projectReceizAssetManifest,
+        projectSportsCard: projectReceizSportsCardManifest,
+    };
+    schemas = RECEIZ_SCHEMAS;
+    projections = {
+        assetManifest: projectReceizAssetManifest,
+        sportsCardManifest: projectReceizSportsCardManifest,
+    };
+    proofMemory = {
+        createRegister: createReceizProofRegister,
     };
     constructor(options = {}) {
         this.baseUrl = trimTrailingSlash(options.baseUrl ?? RECEIZ_DEFAULT_BASE_URL);
@@ -290,6 +393,10 @@ export class ReceizClient {
             throw new Error("receiz_access_token_required");
         return this.request(path, { ...options, bearerToken: this.accessToken });
     }
+    async continueReceizId(identity, options = {}) {
+        const body = await buildReceizIdContinueRequest(identity, options);
+        return this.request("/api/auth/receiz-id/continue", { method: "POST", body });
+    }
     authorizeUrl(options) {
         const url = new URL(`${this.baseUrl}/api/oidc/authorize`);
         url.searchParams.set("response_type", options.responseType ?? "code");
@@ -417,6 +524,350 @@ export function isReceizWebhookEvent(value) {
         return false;
     }
 }
+function stringField(record, key) {
+    if (!record)
+        return null;
+    const value = record[key];
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function numberField(record, key) {
+    if (!record)
+        return null;
+    const value = record[key];
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string" && value.trim() && Number.isFinite(Number(value)))
+        return Number(value);
+    return null;
+}
+function firstString(...values) {
+    for (const value of values) {
+        if (typeof value === "string" && value.trim())
+            return value.trim();
+    }
+    return null;
+}
+function objectField(record, key) {
+    if (!record)
+        return null;
+    const value = record[key];
+    return isRecord(value) ? value : null;
+}
+function optionalCount(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string" && Number.isFinite(Number(value)))
+        return Number(value);
+    return 0;
+}
+function formatUsdCents(value) {
+    if (typeof value !== "string" && typeof value !== "number")
+        return null;
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric))
+        return null;
+    return `$${(numeric / 100).toFixed(2)}`;
+}
+function proofCreatedAt(proof) {
+    return firstString(stringField(proof, "ts"), stringField(proof, "createdAt"));
+}
+function proofKaiUpulse(proof) {
+    return firstString(stringField(proof, "kaiUpulse"), stringField(proof, "kaiPulse"), stringField(proof, "kaiPulseEternal")) ?? numberField(proof, "kaiPulseEternal");
+}
+function addProjectionRow(rows, label, value, href) {
+    if (value === null || value === undefined || value === "")
+        return;
+    rows.push({ label, value: String(value), href: href ?? null });
+}
+export function projectReceizAssetManifest(value) {
+    const manifest = assertReceizAssetManifest(value);
+    const owner = manifest.owner ?? null;
+    const media = manifest.media ?? null;
+    const settlement = manifest.settlement ?? null;
+    const verifyUrl = firstString(manifest.links.verify, manifest.proof.verifyUrl, manifest.proof.verifyPath);
+    const primaryUrl = firstString(manifest.links.open, manifest.links.public, manifest.links.verify, verifyUrl);
+    const mediaUrl = firstString(stringField(media, "url"), stringField(media, "src"), stringField(media, "imageUrl"));
+    const ownerLabel = firstString(stringField(owner, "displayName"), stringField(owner, "ownerLabel"), stringField(owner, "username"), stringField(owner, "receizSubject"));
+    const title = firstString(stringField(media, "title"), stringField(media, "name"), manifest.assetId) ?? manifest.assetId;
+    const proofKind = manifest.proof.kind;
+    const settlementState = firstString(stringField(settlement, "state"), stringField(settlement, "status"));
+    const rows = [];
+    addProjectionRow(rows, "Asset ID", manifest.assetId);
+    addProjectionRow(rows, "Asset Type", manifest.assetType);
+    addProjectionRow(rows, "Proof Kind", proofKind);
+    addProjectionRow(rows, "Verify", verifyUrl, verifyUrl);
+    addProjectionRow(rows, "Kai Pulse", proofKaiUpulse(manifest.proof));
+    addProjectionRow(rows, "Appends", manifest.appends?.length ?? 0);
+    addProjectionRow(rows, "Settlement", settlementState);
+    addProjectionRow(rows, "Owner", ownerLabel);
+    return {
+        schema: "receiz.sdk.asset_manifest_projection.v1",
+        assetId: manifest.assetId,
+        assetType: manifest.assetType,
+        title,
+        subtitle: ownerLabel ? `${manifest.assetType} / ${ownerLabel}` : manifest.assetType,
+        proofKind,
+        verifyUrl,
+        primaryUrl,
+        mediaUrl,
+        ownerLabel,
+        appendCount: manifest.appends?.length ?? 0,
+        settlementState,
+        rows,
+        manifest,
+    };
+}
+export function projectReceizSportsCardManifest(value) {
+    const manifest = assertReceizSportsCardManifest(value);
+    const card = manifest.card;
+    const ownership = manifest.ownership;
+    const valueBasis = manifest.valueBasis;
+    const appendSummary = manifest.appendSummary ?? null;
+    const eventProofSummary = manifest.eventProofSummary ?? null;
+    const title = firstString(stringField(card, "playerName"), stringField(card, "athleteName"), stringField(card, "name"), manifest.collectibleId) ?? manifest.collectibleId;
+    const rarity = firstString(stringField(card, "rarity"), stringField(card, "tier"), stringField(card, "edition"));
+    const team = firstString(stringField(card, "team"), stringField(card, "club"));
+    const verifyUrl = firstString(manifest.links.verify, manifest.links.proof, manifest.links.asset);
+    const eventProofUrl = firstString(manifest.links.eventProof, stringField(eventProofSummary, "latestEventProofUrl"), stringField(eventProofSummary, "latestProofUrl"));
+    const mediaUrl = firstString(stringField(card, "deterministicImageUrl"), stringField(card, "imageUrl"), stringField(card, "mediaUrl"));
+    const ownerLabel = firstString(stringField(ownership, "ownerLabel"), stringField(ownership, "displayName"), stringField(ownership, "ownerSubject"));
+    const scoreLabel = firstString(stringField(valueBasis, "score"), stringField(valueBasis, "valueScore"));
+    const valueLabel = firstString(stringField(valueBasis, "valueLabel"), stringField(valueBasis, "reserveLabel"), formatUsdCents(valueBasis.reserveUsdCents));
+    const appendCount = optionalCount(appendSummary?.count);
+    const eventProofCount = optionalCount(eventProofSummary?.count);
+    const rows = [];
+    addProjectionRow(rows, "Collectible ID", manifest.collectibleId);
+    addProjectionRow(rows, "Claim Hash", manifest.claimHash);
+    addProjectionRow(rows, "Sport", manifest.sport);
+    addProjectionRow(rows, "Owner", ownerLabel);
+    addProjectionRow(rows, "Score", scoreLabel);
+    addProjectionRow(rows, "Reserve", valueLabel);
+    addProjectionRow(rows, "Kai Upulse", firstString(stringField(valueBasis, "kaiUpulse"), stringField(valueBasis, "kaiPulse")));
+    addProjectionRow(rows, "Appends", appendCount);
+    addProjectionRow(rows, "Event Proofs", eventProofCount);
+    addProjectionRow(rows, "Latest Event", stringField(eventProofSummary, "latestEventType"));
+    addProjectionRow(rows, "Proof", verifyUrl, verifyUrl);
+    return {
+        schema: "receiz.sdk.sports_card_manifest_projection.v1",
+        sport: manifest.sport,
+        collectibleId: manifest.collectibleId,
+        claimHash: manifest.claimHash,
+        title,
+        subtitle: [manifest.sport, team, rarity].filter(Boolean).join(" / "),
+        verifyUrl,
+        eventProofUrl,
+        mediaUrl,
+        ownerLabel,
+        scoreLabel,
+        valueLabel,
+        appendCount,
+        eventProofCount,
+        rows,
+        manifest,
+    };
+}
+function normalizeKaiForCompare(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    return trimmed.replace(/^\+/, "");
+}
+function compareNumericTextDesc(leftValue, rightValue) {
+    const left = normalizeKaiForCompare(leftValue);
+    const right = normalizeKaiForCompare(rightValue);
+    if (!left && !right)
+        return 0;
+    if (!left)
+        return 1;
+    if (!right)
+        return -1;
+    const [leftWholeRaw = "", leftFractionRaw = ""] = left.split(".");
+    const [rightWholeRaw = "", rightFractionRaw = ""] = right.split(".");
+    const leftWhole = leftWholeRaw.replace(/^0+/, "") || "0";
+    const rightWhole = rightWholeRaw.replace(/^0+/, "") || "0";
+    if (leftWhole.length !== rightWhole.length)
+        return rightWhole.length - leftWhole.length;
+    if (leftWhole !== rightWhole)
+        return rightWhole.localeCompare(leftWhole);
+    const maxFractionLength = Math.max(leftFractionRaw.length, rightFractionRaw.length);
+    const leftFraction = leftFractionRaw.padEnd(maxFractionLength, "0");
+    const rightFraction = rightFractionRaw.padEnd(maxFractionLength, "0");
+    return rightFraction.localeCompare(leftFraction);
+}
+function compareRegisterEntries(left, right) {
+    const kai = compareNumericTextDesc(left.kaiUpulse, right.kaiUpulse);
+    if (kai !== 0)
+        return kai;
+    const leftTime = left.createdAt ? Date.parse(left.createdAt) : Number.NaN;
+    const rightTime = right.createdAt ? Date.parse(right.createdAt) : Number.NaN;
+    if (Number.isFinite(leftTime) && Number.isFinite(rightTime) && leftTime !== rightTime)
+        return rightTime - leftTime;
+    if (Number.isFinite(leftTime) && !Number.isFinite(rightTime))
+        return -1;
+    if (!Number.isFinite(leftTime) && Number.isFinite(rightTime))
+        return 1;
+    return left.id.localeCompare(right.id);
+}
+function mergeJsonPreservingExisting(existing, incoming) {
+    const merged = { ...existing };
+    for (const [key, value] of Object.entries(incoming)) {
+        if (merged[key] === undefined)
+            merged[key] = value;
+    }
+    return merged;
+}
+function mergeOptionalJsonPreservingExisting(existing, incoming) {
+    if (existing && incoming)
+        return mergeJsonPreservingExisting(existing, incoming);
+    return existing ?? incoming ?? null;
+}
+function normalizeRegisterEntry(value) {
+    const record = ensureRecord(value, "ReceizProofRegisterEntry");
+    const issues = [];
+    const id = ensureString(record, "id", issues);
+    const kind = ensureString(record, "kind", issues);
+    if (!isRecord(record.payload))
+        issues.push("payload must be an object");
+    const createdAt = record.createdAt === null || record.createdAt === undefined ? null : ensureString(record, "createdAt", issues);
+    const kaiUpulse = record.kaiUpulse;
+    if (kaiUpulse !== null && kaiUpulse !== undefined && typeof kaiUpulse !== "string" && typeof kaiUpulse !== "number") {
+        issues.push("kaiUpulse must be a string, number, or null");
+    }
+    const proof = record.proof;
+    if (proof !== null && proof !== undefined && !isRecord(proof))
+        issues.push("proof must be an object or null");
+    const projection = record.projection;
+    if (projection !== null && projection !== undefined && !isRecord(projection))
+        issues.push("projection must be an object or null");
+    failIfIssues("ReceizProofRegisterEntry", issues);
+    return {
+        id: id ?? "",
+        kind: kind ?? "",
+        createdAt,
+        kaiUpulse: kaiUpulse === undefined ? null : kaiUpulse,
+        proof: isRecord(proof) ? proof : null,
+        payload: record.payload,
+        projection: isRecord(projection) ? projection : null,
+    };
+}
+function mergeRegisterEntry(existing, incoming) {
+    return {
+        id: existing.id,
+        kind: existing.kind,
+        createdAt: existing.createdAt ?? incoming.createdAt ?? null,
+        kaiUpulse: existing.kaiUpulse ?? incoming.kaiUpulse ?? null,
+        proof: mergeOptionalJsonPreservingExisting(existing.proof, incoming.proof),
+        payload: mergeJsonPreservingExisting(existing.payload, incoming.payload),
+        projection: mergeOptionalJsonPreservingExisting(existing.projection, incoming.projection),
+    };
+}
+function registerEntryFromAssetManifest(manifest) {
+    const projection = projectReceizAssetManifest(manifest);
+    return {
+        id: `asset:${manifest.assetId}`,
+        kind: "asset_manifest",
+        createdAt: proofCreatedAt(manifest.proof),
+        kaiUpulse: proofKaiUpulse(manifest.proof),
+        proof: manifest.proof,
+        payload: manifest,
+        projection: projection,
+    };
+}
+function registerEntryFromSportsCardManifest(manifest) {
+    const projection = projectReceizSportsCardManifest(manifest);
+    return {
+        id: `sports-card:${manifest.collectibleId}:${manifest.claimHash}`,
+        kind: "sports_card_manifest",
+        createdAt: firstString(stringField(manifest.appendSummary ?? null, "latestObservedAt"), stringField(manifest.ownership, "updatedAt")),
+        kaiUpulse: firstString(stringField(manifest.valueBasis, "kaiUpulse"), stringField(manifest.valueBasis, "kaiPulse")),
+        proof: {
+            claimHash: manifest.claimHash,
+            latestAppendHash: stringField(manifest.appendSummary ?? null, "latestAppendHash"),
+            latestProofHash: stringField(manifest.eventProofSummary ?? null, "latestProofHash"),
+        },
+        payload: manifest,
+        projection: projection,
+    };
+}
+function registerEntryFromWebhookEvent(event) {
+    const proofBundle = objectField(event.data, "proofBundle");
+    const assetId = stringField(event.data, "assetId");
+    const appendId = stringField(event.data, "appendId");
+    return {
+        id: `webhook:${event.id}`,
+        kind: event.type,
+        createdAt: event.createdAt,
+        kaiUpulse: proofKaiUpulse(proofBundle),
+        proof: proofBundle,
+        payload: event,
+        projection: {
+            eventId: event.id,
+            type: event.type,
+            assetId,
+            appendId,
+            verifyUrl: stringField(proofBundle, "verifyUrl"),
+        },
+    };
+}
+export class ReceizProofRegister {
+    ownerId;
+    createdAt;
+    entriesById = new Map();
+    constructor(input = {}) {
+        this.ownerId = input.ownerId ?? null;
+        this.createdAt = input.createdAt ?? new Date().toISOString();
+        for (const entry of input.entries ?? [])
+            this.append(entry);
+    }
+    append(entry) {
+        const normalized = normalizeRegisterEntry(entry);
+        const existing = this.entriesById.get(normalized.id);
+        this.entriesById.set(normalized.id, existing ? mergeRegisterEntry(existing, normalized) : normalized);
+        return this;
+    }
+    admitAssetManifest(value) {
+        return this.append(registerEntryFromAssetManifest(assertReceizAssetManifest(value)));
+    }
+    admitSportsCardManifest(value) {
+        return this.append(registerEntryFromSportsCardManifest(assertReceizSportsCardManifest(value)));
+    }
+    admitWebhookEvent(value) {
+        return this.append(registerEntryFromWebhookEvent(assertReceizWebhookEvent(value)));
+    }
+    has(entryId) {
+        return this.entriesById.has(entryId);
+    }
+    entries() {
+        return [...this.entriesById.values()].sort(compareRegisterEntries);
+    }
+    snapshot() {
+        const entries = this.entries();
+        const head = entries[0] ?? null;
+        return {
+            schema: "receiz.sdk.proof_register.v1",
+            ownerId: this.ownerId,
+            createdAt: this.createdAt,
+            updatedAt: new Date().toISOString(),
+            head: {
+                entryId: head?.id ?? null,
+                kaiUpulse: head?.kaiUpulse ?? null,
+                createdAt: head?.createdAt ?? null,
+                count: entries.length,
+            },
+            entries,
+        };
+    }
+    toJSON() {
+        return this.snapshot();
+    }
+}
+export function createReceizProofRegister(input = {}) {
+    return new ReceizProofRegister(input);
+}
 function bodyToString(body) {
     if (typeof body === "string")
         return body;

package/docs/app-registration-token-lifecycle.md

@@ -17,7 +17,7 @@ const authorizeUrl = receiz.identity.authorizeUrl({
 });
 ```
 
-Receiz Connect uses standard OIDC mechanics for app onboarding and token lifecycle. The identity primitive remains the Receiz subject and account continuity behind the token; the token is permission for delegated API calls, not the identity proof root.
+Receiz Connect is delegated API access. It uses standard OIDC mechanics for app onboarding and token lifecycle, but it is not the identity proof root. Receiz ID, Receiz Key, Identity Record, and Identity Seal remain the identity primitives; Connect tokens authorize scoped API calls after that proof boundary.
 
 Lifecycle:
 

package/docs/identity-login-and-recovery.md

@@ -0,0 +1,122 @@
+# Identity Login And Recovery
+
+```bash
+npm install @receiz/sdk
+```
+
+```ts
+import {
+  buildReceizIdContinueRequest,
+  createReceizClient,
+  createReceizIdIdentity,
+  projectReceizIdentityAccount,
+  readReceizIdentityArtifact,
+  signReceizIdentityLoginProof,
+  verifyReceizIdentityLoginProof,
+} from "@receiz/sdk";
+```
+
+Receiz ID, Receiz Key, Identity Record, and Identity Seal are identity primitives. They carry proof-bearing account continuity. Your app should verify and project them locally first, then ask Receiz only for verified additions or delegated API access.
+
+Receiz ID is the default login path. It does not replace PBI/passkey, email magic-link recovery, or OIDC/Connect. PBI/passkey can still create or recover a Receiz account, email can still recover the account, Receiz Key / Identity Record / Identity Seal can still restore it locally, and OIDC/Connect still delegates API access after identity proof. These rails bind to the same account; they are not parallel account models.
+
+## Create A Fresh Receiz ID
+
+```ts
+const identity = await createReceizIdIdentity({
+  username: "builder",
+  displayName: "Builder",
+  deviceName: "Builder's device",
+});
+
+const account = await projectReceizIdentityAccount(identity.keyFile);
+
+if (!account.portableStateVerified) {
+  throw new Error("Receiz ID account-state proof failed");
+}
+```
+
+Persist the returned identity artifact in your app's durable proof memory. It is not a temporary session object.
+
+## Login With A Receiz Key Or Identity Image
+
+```ts
+const keyFile = await readReceizIdentityArtifact(fileOrImageBytes);
+const account = await projectReceizIdentityAccount(keyFile);
+
+if (!account.portableStateVerified) {
+  throw new Error("Receiz identity artifact proof failed");
+}
+
+renderSignedInShell({
+  userId: account.owner.uid,
+  username: account.owner.username,
+  displayName: account.owner.displayName,
+  domains: account.domains,
+});
+```
+
+`readReceizIdentityArtifact` accepts Receiz Key JSON, Identity Record image bytes, or Identity Seal image bytes. The projection is local verified truth; do not block first paint on a server rediscovery pass.
+
+## Prove Control To Your App
+
+```ts
+const proof = await signReceizIdentityLoginProof({
+  keyFile,
+  challengeText: "YOUR_APP_LOGIN_V1\nnonce=server-issued-nonce",
+});
+
+const ok = await verifyReceizIdentityLoginProof({
+  keyFile,
+  challengeB64Url: proof.challengeB64Url,
+  signatureB64Url: proof.signatureB64Url,
+});
+
+if (!ok) throw new Error("Receiz identity signature failed");
+```
+
+Use a fresh challenge from your own app server when you need server-side session issuance. The proof verifies ownership of the Receiz identity key; it does not make your app the authority over Receiz truth.
+
+## Publish Continuity To Receiz
+
+```ts
+const receiz = createReceizClient({ baseUrl: "https://receiz.com" });
+
+const response = await receiz.identity.continueReceizId(identity, {
+  next: "/profile",
+});
+```
+
+This calls the existing Receiz ID continuation route. It publishes the same signed proof the Receiz app uses for real account creation/recovery. Use it when your app needs Receiz infrastructure to append global continuity or issue a Receiz session.
+
+When a user has already recovered with PBI/passkey or email, use Receiz ID continuation as the bound default for the same account. Do not remove the recovery rail from your app just because the Receiz ID path is default.
+
+For server-side publication, build the request explicitly:
+
+```ts
+const body = await buildReceizIdContinueRequest(identity, {
+  next: "/profile",
+});
+
+await fetch("https://receiz.com/api/auth/receiz-id/continue", {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify(body),
+});
+```
+
+## Connect After Proof Login
+
+Use Connect only when your app needs delegated Receiz API access.
+
+```ts
+const connectUrl = receiz.identity.authorizeUrl({
+  clientId: process.env.RECEIZ_CLIENT_ID!,
+  redirectUri: "https://app.example.com/auth/receiz/callback",
+  codeChallenge,
+  scope: ["openid", "profile", "receiz:wallet.transfer"],
+  state,
+});
+```
+
+Connect tokens authorize API calls beneath the identity primitive. They are permission artifacts, not the proof root.