@receiz/sdk 93.2.0 → 95.0.0

package/README.md

@@ -21,12 +21,19 @@ const receiz = createReceizClient({
 
 The SDK is convenience, not authority. It reads public API projections, sends delegated actions, validates developer manifests, and verifies webhook delivery signatures. Sealed artifacts, proof bundles, verified appends, ownership appends, and settlement ledger records remain the stronger source of truth.
 
+Kai Klok is the proof object state machine. `kaiPulseEternal` is the pulse unit carried by that state machine. A complete Receiz proof object carries Kai; without its Kai coordinate it is not complete Receiz proof truth.
+
+Receiz ID is the default account-continuity rail for everyday login. It does not replace PBI/passkey, email magic-link recovery, Receiz Key, Identity Record, Identity Seal, or OIDC/Connect. Those rails all preserve the same account when bound: PBI/passkey can create or recover a Receiz account, email can recover the account, Receiz identity artifacts can restore it locally, and OIDC/Connect can delegate API access after identity proof.
+
+Receiz Key, Identity Record, and Identity Seal are Receiz identity primitives exposed through the SDK for developer apps. Their current account-state envelope is `receiz.account.state.v3`; it carries admitted account proof memory across profile, action ledger, calendar, wallet settlement, Sports vault/cards/appends/event proofs, and related entries. The SDK mirrors the same law for developer apps through local proof registers: admit verified truth once, persist it, and ask Receiz only for verified additions after the known head. Connect is delegated API access; it is not the identity proof root.
+
 Default integration order:
 
 1. Verify first, then project.
 2. Render the proof object or manifest as the user-facing truth.
 3. Append public proof, wallet, sports, or Connect additions after the known truth.
-4. Never treat an SDK response as stronger than the sealed artifact, verified append, ownership append, or settlement primitive it projects.
+4. Order proof objects by Kai/Klok state; render Chronos only as display.
+5. Never treat an SDK response as stronger than the sealed artifact, verified append, ownership append, or settlement primitive it projects.
 
 ## Five-Minute Proof Object App
 
@@ -82,6 +89,43 @@ const snapshot = memory.snapshot();
 
 Use schemas for developer validation, projections for display-ready proof rows, and proof memory for first-admission-then-append-forever UX.
 
+## Receiz ID Account Creation And Recovery
+
+Developers can let users create a fresh Receiz ID account, recover from a Receiz Key, or login with an Identity Record / Identity Seal image without inventing a parallel login model. Receiz ID is the default login path, but it does not replace the existing rails: PBI/passkey stays available for account creation, account recovery, and account signing; email magic-link stays available for recovery; OIDC/Connect stays available for delegated API access. The result is one account, not separate accounts for each rail.
+
+```ts
+import {
+  buildReceizIdContinueRequest,
+  createReceizIdIdentity,
+  projectReceizIdentityAccount,
+  readReceizIdentityArtifact,
+  signReceizIdentityLoginProof,
+} from "@receiz/sdk";
+
+const identity = await createReceizIdIdentity({
+  username: "builder",
+  displayName: "Builder",
+});
+
+const keyFile = await readReceizIdentityArtifact(fileOrImageBytes);
+const account = await projectReceizIdentityAccount(keyFile);
+
+if (!account.portableStateVerified) throw new Error("identity proof failed");
+
+const proof = await signReceizIdentityLoginProof({
+  keyFile,
+  challengeText: "your-app-login-challenge",
+});
+
+const receizPublication = await buildReceizIdContinueRequest(identity, {
+  next: "/profile",
+});
+```
+
+Use the local projection for first paint in your app. Send the continuation request to Receiz only when you need Receiz infrastructure to append global continuity or issue a Receiz session. Use Connect after proof login when your app needs delegated Receiz API access.
+
+Full quickstart: `docs/identity-login-and-recovery.md`.
+
 ## Artifact Verification
 
 ```ts

package/dist/identity.d.ts

@@ -0,0 +1,172 @@
+export declare const RECEIZ_KEY_SCHEMA = "receiz.key.v1";
+export declare const RECEIZ_KEY_NAME = "Receiz Key";
+export declare const RECEIZ_ACCOUNT_STATE_SCHEMA = "receiz.account.state.v3";
+export declare const RECEIZ_DEVICE_IDENTITY_SCHEMA = "receiz.device.identity.v1";
+export declare const RECEIZ_IDENTITY_LOGIN_PROOF_SCHEMA = "receiz.identity.login_proof.v1";
+export declare const RECEIZ_IDENTITY_ACCOUNT_PROJECTION_SCHEMA = "receiz.sdk.identity_account_projection.v1";
+export declare const RECEIZ_IDENTITY_RECORD_KEY_CHUNK_KEY = "receiz.identity_record.keyfile.v1";
+export type ReceizIdentityKeyAlgorithm = "Ed25519" | "P-256";
+export type ReceizPortableStateProofMethod = "ed25519.jcs.v1" | "ecdsa-p256-sha256.jcs.v1";
+export type ReceizKeyOwner = {
+    uid: string;
+    email: string | null;
+    username: string | null;
+    displayName: string | null;
+};
+export type ReceizPortableStateProof = {
+    method: ReceizPortableStateProofMethod;
+    digestSha256Hex: string;
+    signatureB64u: string;
+    signedAt: string;
+};
+export type ReceizPortableState = {
+    schema: string;
+    exportedAt: string;
+    snapshot: unknown;
+    proof: ReceizPortableStateProof | null;
+};
+export type ReceizKeyAttestation = {
+    pbiDecision: string;
+    pbiReceiptHash: string;
+    pbiChallengeId: string;
+    pbiRequestId: string | null;
+    attestedAt: string;
+};
+export type ReceizKeyFileV1 = {
+    schema: typeof RECEIZ_KEY_SCHEMA;
+    name: typeof RECEIZ_KEY_NAME;
+    version: 1;
+    issuedAt: string;
+    keyId: string;
+    alg: ReceizIdentityKeyAlgorithm;
+    owner: ReceizKeyOwner;
+    crypto: {
+        publicKeyRawB64u: string;
+        privateKeyPkcs8CiphertextB64u: string;
+        privateKeyPkcs8B64u?: string | null;
+        kdf: {
+            name: "PBKDF2-SHA256";
+            iterations: number;
+            saltB64u: string;
+        };
+        cipher: {
+            name: "AES-GCM-256";
+            ivB64u: string;
+            aad: string;
+        };
+    };
+    attestation: ReceizKeyAttestation | null;
+    portableState: ReceizPortableState | null;
+};
+export type ReceizKeyFile = ReceizKeyFileV1;
+export type ReceizDeviceIdentity = {
+    schema: typeof RECEIZ_DEVICE_IDENTITY_SCHEMA;
+    createdAt: string;
+    updatedAt: string;
+    localUid: string;
+    username: string;
+    displayName: string;
+    deviceName: string | null;
+    keyFile: ReceizKeyFile;
+};
+export type ReceizIdIdentityOptions = {
+    username?: string | null | undefined;
+    displayName?: string | null | undefined;
+    deviceName?: string | null | undefined;
+    createdAt?: string | undefined;
+    passphrase?: string | undefined;
+    allowP256Fallback?: boolean | undefined;
+    pbkdf2Iterations?: number | undefined;
+};
+export type ReceizIdentityLoginProof = {
+    schema: typeof RECEIZ_IDENTITY_LOGIN_PROOF_SCHEMA;
+    keyId: string;
+    alg: ReceizIdentityKeyAlgorithm;
+    challengeB64Url: string;
+    signatureB64Url: string;
+};
+export type ReceizIdentityLoginProofInput = {
+    keyFile: ReceizKeyFile;
+    passphrase?: string | undefined;
+    challengeText?: string | undefined;
+    challengeB64Url?: string | undefined;
+};
+export type ReceizIdContinueRequest = {
+    keyId: string;
+    alg: ReceizIdentityKeyAlgorithm;
+    publicKeyRawB64u: string;
+    localUid: string;
+    username: string;
+    displayName: string;
+    deviceName: string | null;
+    createdAt: string;
+    challengeB64Url: string;
+    signatureB64Url: string;
+    next?: string;
+};
+export type ReceizIdContinueOptions = {
+    next?: string | undefined;
+    nowMs?: number | undefined;
+    nonceB64Url?: string | undefined;
+    passphrase?: string | undefined;
+};
+export type ReceizIdentityAccountProjection = {
+    schema: typeof RECEIZ_IDENTITY_ACCOUNT_PROJECTION_SCHEMA;
+    keyId: string;
+    alg: ReceizIdentityKeyAlgorithm;
+    owner: ReceizKeyOwner;
+    accountStateSchema: string | null;
+    portableStateVerified: boolean;
+    portableStateStatus: "verified" | "missing" | "invalid";
+    snapshot: unknown;
+    domains: {
+        profile: boolean;
+        actionLedger: boolean;
+        calendar: boolean;
+        wallet: boolean;
+        sports: boolean;
+    };
+};
+export declare function receizBase64UrlEncode(bytes: Uint8Array): string;
+export declare function receizBase64UrlDecode(value: string): Uint8Array;
+export declare function parseReceizIdentityArtifactText(text: string): ReceizKeyFileV1;
+export declare function appendReceizIdentityArtifactTrailerToPng(pngBytes: Uint8Array, keyFile: ReceizKeyFile): Uint8Array;
+export declare function readReceizIdentityArtifact(input: Blob | ArrayBuffer | Uint8Array | string): Promise<ReceizKeyFileV1>;
+export declare function serializeReceizIdentityArtifact(keyFile: ReceizKeyFile): string;
+export declare function deriveReceizIdentityKeyIdFromPublicKeyRawB64u(publicKeyRawB64u: string, alg?: ReceizIdentityKeyAlgorithm): Promise<string>;
+export declare function createReceizIdentityKeyFile(args: {
+    passphrase?: string | undefined;
+    owner: {
+        uid: string;
+        email?: string | null;
+        username?: string | null;
+        displayName?: string | null;
+    };
+    portableState?: {
+        schema?: string;
+        snapshot: unknown;
+    } | null;
+    issuedAt?: string | undefined;
+    pbkdf2Iterations?: number | undefined;
+    allowP256Fallback?: boolean | undefined;
+}): Promise<{
+    keyFile: ReceizKeyFileV1;
+    keyId: string;
+    publicKeyRawB64u: string;
+    alg: ReceizIdentityKeyAlgorithm;
+}>;
+export declare function createReceizIdIdentity(options?: ReceizIdIdentityOptions): Promise<ReceizDeviceIdentity>;
+export declare function decryptReceizIdentityPrivateSigningKey(args: {
+    keyFile: ReceizKeyFile;
+    passphrase?: string | undefined;
+}): Promise<CryptoKey>;
+export declare function signReceizIdentityLoginProof(input: ReceizIdentityLoginProofInput): Promise<ReceizIdentityLoginProof>;
+export declare function verifyReceizIdentityLoginProof(args: {
+    keyFile: ReceizKeyFile;
+    challengeB64Url: string;
+    signatureB64Url: string;
+}): Promise<boolean>;
+export declare function verifyReceizIdentityPortableStateProof(keyFileInput: ReceizKeyFile): Promise<"verified" | "missing" | "invalid">;
+export declare function buildReceizIdContinueRequest(identity: ReceizDeviceIdentity, options?: ReceizIdContinueOptions): Promise<ReceizIdContinueRequest>;
+export declare function projectReceizIdentityAccount(keyFileInput: ReceizKeyFile): Promise<ReceizIdentityAccountProjection>;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"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"}