@calimero-network/mero-js 26.10.0 → 27.0.0

package/dist/cloud-v2/errors.d.ts

@@ -0,0 +1,98 @@
+/**
+ * What the cloud node's refusals mean to a caller (spec D64, D70).
+ *
+ * The node answers an error as `{ error: CODE, message, details }` with an HTTP
+ * status. {@link errorFrom} is the one place the client turns that into an
+ * error a caller can switch on; every call, view and event stream goes through
+ * it. It matches the status and the code together, never the status alone: the
+ * node sends other 409s (`CONFLICT`, `NOT_INSTALLED`) that are not an
+ * idempotency mismatch, and other 413s (`TOO_LARGE` from the sealed transport)
+ * that are not oversized call arguments. Anything it does not recognise stays a
+ * plain {@link CalimeroError} carrying both.
+ *
+ * Every typed error extends {@link CalimeroError}, so `instanceof CalimeroError`
+ * and its `status` and `code` (the node's code) keep working for all of them.
+ */
+export declare class CalimeroError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details: Record<string, unknown>;
+    constructor(status: number, code: string, message: string, details?: Record<string, unknown>);
+}
+/** `401 UNAUTHENTICATED`: sign in (again) and repeat the request. */
+export declare class LoginRequired extends CalimeroError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * `404 NOT_FOUND`: what the request names does not exist for this caller. For
+ * an app this does not say whether it exists: an account the app does not
+ * admit gets the same answer as a missing app.
+ */
+export declare class NotFound extends CalimeroError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * `412 CONFIRM_REQUIRED`: the call needs the account holder's passkey over a
+ * challenge in `details`. The `*Confirmed` methods answer it themselves; it
+ * reaches a caller only from a method that was given no passkey.
+ */
+export declare class ConfirmRequired extends CalimeroError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/** The user declined the passkey prompt a confirmation asked for. Nothing was sent. */
+export declare class ConfirmCancelled extends Error {
+    readonly cause?: unknown;
+    constructor(cause?: unknown);
+}
+/** `413 ARGS_TOO_LARGE`: the call's arguments are over the node's limit; it did not run. */
+export declare class ArgsTooLarge extends CalimeroError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/** `409 IDEMPOTENCY_MISMATCH`: the idempotency key was used before with different arguments. */
+export declare class IdempotencyMismatch extends CalimeroError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * `422 APP_ERROR`: the app refused the call. `appCode` is the app's declared
+ * error (`Taken`, `Forbidden`, ...) and `fields` its named fields. The call was
+ * logged, so its idempotency key is spent.
+ */
+export declare class AppError extends CalimeroError {
+    readonly appCode: string;
+    readonly fields: Record<string, unknown>;
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/** `422 TRAP`: the run trapped (`OutOfFuel`, `OutOfMemory`, ...). The call was logged. */
+export declare class TrapError extends CalimeroError {
+    readonly kind: string;
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Whether a call the node answered 503 may have committed: `false` when the
+ * node says it did not (`TIMEOUT`, `MIGRATING`), `"unknown"` otherwise (a call
+ * that raced a leader change). Never a plain boolean: `"unknown"` must not read
+ * as "no".
+ */
+export type Committed = false | 'unknown';
+/**
+ * Any `503`, or a connection that failed, after the client's retries with the
+ * same idempotency key ran out. `reason` is the node's code in lower case
+ * (`timeout`, `migrating`, `unavailable`, ...), or `network` when the node gave
+ * no answer at all (code `NETWORK`, `cause` the `fetch` failure); such a call
+ * may have committed, so its `committed` is `'unknown'`.
+ */
+export declare class UnavailableError extends CalimeroError {
+    readonly reason: string;
+    readonly committed: Committed;
+    /** Seconds the node asked to wait, when it said. */
+    readonly retryAfter: number | undefined;
+    /** What failed, when the node gave no answer. */
+    readonly cause: unknown;
+    constructor(code: string, message: string, details?: Record<string, unknown>, retryAfter?: number, cause?: unknown);
+}
+/**
+ * The error for a refusal the node answered with `status` and `body` (its JSON
+ * `{ error, message, details }`, or whatever it sent). The one place statuses
+ * become typed errors.
+ */
+export declare function errorFrom(status: number, body: unknown, retryAfterHeader?: string | null): CalimeroError;

package/dist/cloud-v2/errors.js

@@ -0,0 +1,165 @@
+/**
+ * What the cloud node's refusals mean to a caller (spec D64, D70).
+ *
+ * The node answers an error as `{ error: CODE, message, details }` with an HTTP
+ * status. {@link errorFrom} is the one place the client turns that into an
+ * error a caller can switch on; every call, view and event stream goes through
+ * it. It matches the status and the code together, never the status alone: the
+ * node sends other 409s (`CONFLICT`, `NOT_INSTALLED`) that are not an
+ * idempotency mismatch, and other 413s (`TOO_LARGE` from the sealed transport)
+ * that are not oversized call arguments. Anything it does not recognise stays a
+ * plain {@link CalimeroError} carrying both.
+ *
+ * Every typed error extends {@link CalimeroError}, so `instanceof CalimeroError`
+ * and its `status` and `code` (the node's code) keep working for all of them.
+ */
+export class CalimeroError extends Error {
+    constructor(status, code, message, details = {}) {
+        super(`${status} ${code}: ${message}`);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.name = 'CalimeroError';
+    }
+}
+/** `401 UNAUTHENTICATED`: sign in (again) and repeat the request. */
+export class LoginRequired extends CalimeroError {
+    constructor(message, details = {}) {
+        super(401, 'UNAUTHENTICATED', message, details);
+        this.name = 'LoginRequired';
+    }
+}
+/**
+ * `404 NOT_FOUND`: what the request names does not exist for this caller. For
+ * an app this does not say whether it exists: an account the app does not
+ * admit gets the same answer as a missing app.
+ */
+export class NotFound extends CalimeroError {
+    constructor(message, details = {}) {
+        super(404, 'NOT_FOUND', message, details);
+        this.name = 'NotFound';
+    }
+}
+/**
+ * `412 CONFIRM_REQUIRED`: the call needs the account holder's passkey over a
+ * challenge in `details`. The `*Confirmed` methods answer it themselves; it
+ * reaches a caller only from a method that was given no passkey.
+ */
+export class ConfirmRequired extends CalimeroError {
+    constructor(message, details = {}) {
+        super(412, 'CONFIRM_REQUIRED', message, details);
+        this.name = 'ConfirmRequired';
+    }
+}
+/** The user declined the passkey prompt a confirmation asked for. Nothing was sent. */
+export class ConfirmCancelled extends Error {
+    constructor(cause) {
+        super('the passkey confirmation was cancelled');
+        this.cause = cause;
+        this.name = 'ConfirmCancelled';
+    }
+}
+/** `413 ARGS_TOO_LARGE`: the call's arguments are over the node's limit; it did not run. */
+export class ArgsTooLarge extends CalimeroError {
+    constructor(message, details = {}) {
+        super(413, 'ARGS_TOO_LARGE', message, details);
+        this.name = 'ArgsTooLarge';
+    }
+}
+/** `409 IDEMPOTENCY_MISMATCH`: the idempotency key was used before with different arguments. */
+export class IdempotencyMismatch extends CalimeroError {
+    constructor(message, details = {}) {
+        super(409, 'IDEMPOTENCY_MISMATCH', message, details);
+        this.name = 'IdempotencyMismatch';
+    }
+}
+/**
+ * `422 APP_ERROR`: the app refused the call. `appCode` is the app's declared
+ * error (`Taken`, `Forbidden`, ...) and `fields` its named fields. The call was
+ * logged, so its idempotency key is spent.
+ */
+export class AppError extends CalimeroError {
+    constructor(message, details = {}) {
+        super(422, 'APP_ERROR', message, details);
+        this.name = 'AppError';
+        const { appCode, fields } = appErrorOf(details);
+        this.appCode = appCode;
+        this.fields = fields;
+    }
+}
+/** `422 TRAP`: the run trapped (`OutOfFuel`, `OutOfMemory`, ...). The call was logged. */
+export class TrapError extends CalimeroError {
+    constructor(message, details = {}) {
+        super(422, 'TRAP', message, details);
+        this.name = 'TrapError';
+        this.kind = typeof details.kind === 'string' ? details.kind : '';
+    }
+}
+/**
+ * Any `503`, or a connection that failed, after the client's retries with the
+ * same idempotency key ran out. `reason` is the node's code in lower case
+ * (`timeout`, `migrating`, `unavailable`, ...), or `network` when the node gave
+ * no answer at all (code `NETWORK`, `cause` the `fetch` failure); such a call
+ * may have committed, so its `committed` is `'unknown'`.
+ */
+export class UnavailableError extends CalimeroError {
+    constructor(code, message, details = {}, retryAfter, cause) {
+        super(503, code, message, details);
+        this.name = 'UnavailableError';
+        this.reason = code.toLowerCase();
+        this.committed = code === 'TIMEOUT' || code === 'MIGRATING' ? false : 'unknown';
+        this.retryAfter = retryAfter;
+        this.cause = cause;
+    }
+}
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+/**
+ * The app's code and named fields. The node puts them in `details` as
+ * `{ code, fields }`; an older node nests the app's error under `details.error`.
+ * Positional payloads (`"0"`, `"1"`) are never read as fields (D63).
+ */
+function appErrorOf(details) {
+    const source = typeof details.code === 'string' ? details : record(details.error);
+    const appCode = typeof source.code === 'string' ? source.code : '';
+    return { appCode, fields: { ...record(source.fields) } };
+}
+function retryAfterOf(details, header) {
+    for (const candidate of [details.retryAfter, header == null ? undefined : Number(header)]) {
+        if (typeof candidate === 'number' && Number.isFinite(candidate) && candidate >= 0)
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * The error for a refusal the node answered with `status` and `body` (its JSON
+ * `{ error, message, details }`, or whatever it sent). The one place statuses
+ * become typed errors.
+ */
+export function errorFrom(status, body, retryAfterHeader) {
+    const value = record(body);
+    const code = typeof value.error === 'string' ? value.error : 'ERROR';
+    const message = typeof value.message === 'string' ? value.message : '';
+    const details = record(value.details);
+    if (status === 503)
+        return new UnavailableError(code, message, details, retryAfterOf(details, retryAfterHeader));
+    switch (`${status} ${code}`) {
+        case '401 UNAUTHENTICATED':
+            return new LoginRequired(message, details);
+        case '404 NOT_FOUND':
+            return new NotFound(message, details);
+        case '409 IDEMPOTENCY_MISMATCH':
+            return new IdempotencyMismatch(message, details);
+        case '412 CONFIRM_REQUIRED':
+            return new ConfirmRequired(message, details);
+        case '413 ARGS_TOO_LARGE':
+            return new ArgsTooLarge(message, details);
+        case '422 APP_ERROR':
+            return new AppError(message, details);
+        case '422 TRAP':
+            return new TrapError(message, details);
+        default:
+            return new CalimeroError(status, code, message, details);
+    }
+}

package/dist/cloud-v2/index.d.ts

@@ -0,0 +1,10 @@
+export { CalimeroClient } from './client.js';
+export { AppError, ArgsTooLarge, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, NotFound, TrapError, UnavailableError, errorFrom, } from './errors.js';
+export type { Committed } from './errors.js';
+export type { AppInfo, BlobInfo, CallResult, CalimeroClientOptions, CloudEvent, CalimeroSession, PackageInfo, PackageInstalled, CloudRetryOptions, OrgUpgradeTarget, PresenceEntry, UpgradeRun, ViewResult, } from './client.js';
+export { claimedRelease, fetchAttestedKey, MOCK_QUOTE_HEADER } from './attestation.js';
+export type { AttestationDoc, CloudPolicy, CloudReleasePolicy } from './attestation.js';
+export { browserPasskey, b64url, fromB64url } from './passkey.js';
+export type { AssertionJSON, PasskeyProvider, RegistrationJSON } from './passkey.js';
+export { DEFAULT_ORG_CAPABILITIES, ORG_CAPABILITIES, orgCapabilities } from './capabilities.js';
+export type { OrgCapability } from './capabilities.js';

package/dist/cloud-v2/index.js

@@ -0,0 +1,5 @@
+export { CalimeroClient } from './client.js';
+export { AppError, ArgsTooLarge, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, NotFound, TrapError, UnavailableError, errorFrom, } from './errors.js';
+export { claimedRelease, fetchAttestedKey, MOCK_QUOTE_HEADER } from './attestation.js';
+export { browserPasskey, b64url, fromB64url } from './passkey.js';
+export { DEFAULT_ORG_CAPABILITIES, ORG_CAPABILITIES, orgCapabilities } from './capabilities.js';

package/dist/cloud-v2/passkey.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Passkeys: the browser's WebAuthn API, or anything that answers like it.
+ *
+ * Every binary field crosses the wire as base64url, matching
+ * `calimero-identity`'s `Registration` and `Assertion`.
+ */
+export interface RegistrationJSON {
+    attestationObject: string;
+    clientDataJson: string;
+}
+export interface AssertionJSON {
+    credentialId: string;
+    authenticatorData: string;
+    clientDataJson: string;
+    signature: string;
+}
+/** Something that holds a passkey. */
+export interface PasskeyProvider {
+    /** Answer `navigator.credentials.create` for the node's options. */
+    create(options: Record<string, unknown>): Promise<RegistrationJSON>;
+    /** Sign `challenge` (an assertion), optionally limited to `allowCredentials`. */
+    get(challenge: Uint8Array, rpId: string, allowCredentials?: string[]): Promise<AssertionJSON>;
+}
+export declare function b64url(bytes: Uint8Array): string;
+export declare function fromB64url(s: string): Uint8Array;
+/** The platform authenticator (Touch ID, Face ID, Windows Hello, a security key, a synced passkey). */
+export declare function browserPasskey(): PasskeyProvider;

package/dist/cloud-v2/passkey.js

@@ -0,0 +1,73 @@
+/**
+ * Passkeys: the browser's WebAuthn API, or anything that answers like it.
+ *
+ * Every binary field crosses the wire as base64url, matching
+ * `calimero-identity`'s `Registration` and `Assertion`.
+ */
+export function b64url(bytes) {
+    let bin = '';
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+export function fromB64url(s) {
+    const pad = s.replace(/-/g, '+').replace(/_/g, '/') + '==='.slice((s.length + 3) % 4);
+    const bin = atob(pad);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+const buf = (b) => b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength);
+/** A dismissed prompt, named as WebAuthn names one (`NotAllowedError`), so a confirmation reads it as declined. */
+function cancelled(message) {
+    const error = new Error(message);
+    error.name = 'NotAllowedError';
+    return error;
+}
+/** The platform authenticator (Touch ID, Face ID, Windows Hello, a security key, a synced passkey). */
+export function browserPasskey() {
+    return {
+        async create(options) {
+            const o = options;
+            const cred = (await navigator.credentials.create({
+                publicKey: {
+                    challenge: buf(fromB64url(o.challenge)),
+                    rp: o.rp,
+                    user: { ...o.user, id: buf(fromB64url(o.user.id)) },
+                    pubKeyCredParams: o.pubKeyCredParams,
+                    excludeCredentials: (o.excludeCredentials ?? []).map((c) => ({ type: c.type, id: buf(fromB64url(c.id)) })),
+                    authenticatorSelection: o.authenticatorSelection,
+                    attestation: 'none',
+                    timeout: o.timeout,
+                },
+            }));
+            if (!cred)
+                throw cancelled('passkey creation was cancelled');
+            const r = cred.response;
+            return {
+                attestationObject: b64url(new Uint8Array(r.attestationObject)),
+                clientDataJson: b64url(new Uint8Array(r.clientDataJSON)),
+            };
+        },
+        async get(challenge, rpId, allowCredentials) {
+            const cred = (await navigator.credentials.get({
+                publicKey: {
+                    challenge: buf(challenge),
+                    rpId,
+                    userVerification: 'preferred',
+                    allowCredentials: (allowCredentials ?? []).map((id) => ({ type: 'public-key', id: buf(fromB64url(id)) })),
+                },
+            }));
+            if (!cred)
+                throw cancelled('passkey sign-in was cancelled');
+            const r = cred.response;
+            return {
+                credentialId: b64url(new Uint8Array(cred.rawId)),
+                authenticatorData: b64url(new Uint8Array(r.authenticatorData)),
+                clientDataJson: b64url(new Uint8Array(r.clientDataJSON)),
+                signature: b64url(new Uint8Array(r.signature)),
+            };
+        },
+    };
+}

package/dist/crypto/internal.d.ts

@@ -1,11 +1,7 @@
 /**
- * Byte-level primitives shared by everything in this package that signs.
- *
- * Extracted from `warrant/warrant.ts` when the device-cert signer arrived and
- * needed the same `domainHash`, hex handling and ed25519 import. Keeping one
- * copy is the point: these have to stay byte-identical with core, and two
- * copies drifting apart is exactly the failure the byte-parity e2e exists to
- * catch. Internal — not exported from the package root.
+ * Byte-level primitives shared by the sealed transport, the attestation check
+ * and the agent gate: hex handling, fixed-width integers and concatenation.
+ * Internal — not exported from the package root.
  */
 /** Little-endian u32, for borsh fixed-width fields and epoch counters. */
 export declare function u32le(value: number): Uint8Array;
@@ -24,33 +20,3 @@ export declare function fromHex(value: string, label: string, expectedBytes: num
 export declare function fromHexUnsized(value: string, label: string): Uint8Array;
 export declare function u64le(value: number | bigint): Uint8Array;
 export declare function concat(...parts: Uint8Array[]): Uint8Array;
-/**
- * core's `domain_hash`: SHA-256 over the length-prefixed domain, then each
- * length-prefixed part. The lengths are what stop two different field splits from
- * hashing alike.
- */
-export declare function domainHash(domain: Uint8Array, parts: Uint8Array[]): Promise<Uint8Array>;
-export declare function importSigningKey(secretHex: string): Promise<CryptoKey>;
-/**
- * Check an ed25519 signature against a public key, both raw.
- *
- * The one primitive here that consumes rather than produces a signature: a page
- * handed a credential by another origin has to check it before it acts on it,
- * and "the node will reject it later" is not the same safeguard — by then the
- * page has already stored an account it does not control.
- *
- * `raw` import is the public-key counterpart of the PKCS#8 import above and is
- * available on exactly the runtimes that can sign, so a runtime that got this
- * far will not fail here for lack of support.
- *
- * @param publicKey 64 hex, the key the signature must verify against
- */
-export declare function verifySignature(publicKey: string, signature: Uint8Array, payload: Uint8Array): Promise<boolean>;
-/**
- * The public half of an ed25519 seed.
- *
- * Derived rather than taken as an argument, for the reason core does the same: a
- * caller able to name a key it does not hold could produce a warrant it cannot
- * sign, and the field would stop meaning "who authorised this".
- */
-export declare function derivePublicKey(secretHex: string): Promise<Uint8Array>;

package/dist/crypto/internal.js

@@ -1,16 +1,8 @@
 /**
- * Byte-level primitives shared by everything in this package that signs.
- *
- * Extracted from `warrant/warrant.ts` when the device-cert signer arrived and
- * needed the same `domainHash`, hex handling and ed25519 import. Keeping one
- * copy is the point: these have to stay byte-identical with core, and two
- * copies drifting apart is exactly the failure the byte-parity e2e exists to
- * catch. Internal — not exported from the package root.
+ * Byte-level primitives shared by the sealed transport, the attestation check
+ * and the agent gate: hex handling, fixed-width integers and concatenation.
+ * Internal — not exported from the package root.
  */
-const PKCS8_ED25519_PREFIX = new Uint8Array([
-    0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04,
-    0x22, 0x04, 0x20,
-]);
 /** Little-endian u32, for borsh fixed-width fields and epoch counters. */
 export function u32le(value) {
     const out = new Uint8Array(4);
@@ -69,64 +61,3 @@ export function concat(...parts) {
     }
     return out;
 }
-/**
- * core's `domain_hash`: SHA-256 over the length-prefixed domain, then each
- * length-prefixed part. The lengths are what stop two different field splits from
- * hashing alike.
- */
-export async function domainHash(domain, parts) {
-    const chunks = [u64le(domain.length), domain];
-    for (const part of parts) {
-        chunks.push(u64le(part.length), part);
-    }
-    return new Uint8Array(await crypto.subtle.digest('SHA-256', concat(...chunks)));
-}
-export async function importSigningKey(secretHex) {
-    const seed = fromHex(secretHex, 'deviceSecret', 32);
-    const pkcs8 = concat(PKCS8_ED25519_PREFIX, seed);
-    try {
-        return await crypto.subtle.importKey('pkcs8', pkcs8, { name: 'Ed25519' }, false, ['sign']);
-    }
-    catch (cause) {
-        // The original message is folded in rather than passed as `cause`: this
-        // package targets ES2020, where `Error` has no `cause` option.
-        const detail = cause instanceof Error ? `: ${cause.message}` : '';
-        throw new Error('this runtime has no WebCrypto Ed25519, so a warrant cannot be signed ' +
-            'here. Node 18.4+, Safari 17+, Firefox 129+ and Chrome 137+ have it; ' +
-            'otherwise mint the warrant with `merod account warrant`' +
-            detail);
-    }
-}
-/**
- * Check an ed25519 signature against a public key, both raw.
- *
- * The one primitive here that consumes rather than produces a signature: a page
- * handed a credential by another origin has to check it before it acts on it,
- * and "the node will reject it later" is not the same safeguard — by then the
- * page has already stored an account it does not control.
- *
- * `raw` import is the public-key counterpart of the PKCS#8 import above and is
- * available on exactly the runtimes that can sign, so a runtime that got this
- * far will not fail here for lack of support.
- *
- * @param publicKey 64 hex, the key the signature must verify against
- */
-export async function verifySignature(publicKey, signature, payload) {
-    const key = await crypto.subtle.importKey('raw', fromHex(publicKey, 'publicKey', 32), { name: 'Ed25519' }, false, ['verify']);
-    return crypto.subtle.verify({ name: 'Ed25519' }, key, signature, payload);
-}
-/**
- * The public half of an ed25519 seed.
- *
- * Derived rather than taken as an argument, for the reason core does the same: a
- * caller able to name a key it does not hold could produce a warrant it cannot
- * sign, and the field would stop meaning "who authorised this".
- */
-export async function derivePublicKey(secretHex) {
-    const seed = fromHex(secretHex, 'deviceSecret', 32);
-    const pkcs8 = concat(PKCS8_ED25519_PREFIX, seed);
-    const key = await crypto.subtle.importKey('pkcs8', pkcs8, { name: 'Ed25519' }, true, ['sign']);
-    const jwk = await crypto.subtle.exportKey('jwk', key);
-    const raw = jwk.x;
-    return Uint8Array.from(atob(raw.replace(/-/g, '+').replace(/_/g, '/')), (c) => c.charCodeAt(0));
-}