@calimero-network/mero-js 26.11.0 → 27.0.1

package/dist/cloud/enrol-redirect.js

@@ -1,244 +0,0 @@
-/**
- * Getting an app's device key certified **by a wallet on another origin**.
- *
- * An app holds a device keypair and no account. It cannot certify that key
- * itself: certifying is a signature by an account root, and the root is the one
- * key in the system with nothing above it to revoke it — so a page that can
- * reach it can take the account for good. The whole design is that the app
- * never can.
- *
- * What separates them is the **same-origin policy**, and that is why this is a
- * redirect rather than a message, a popup API or a shared library. The wallet
- * keeps the root as a non-extractable key in *its* origin's IndexedDB; script
- * running on the app's origin cannot read another origin's storage, cannot read
- * its keys, and cannot draw its consent screen. Nothing weaker enforces that —
- * an iframe with a `postMessage` bridge would put the approval dialog inside a
- * document the app can style, overlay and click for you.
- *
- * So the shape is: send the person to the wallet naming the key you want
- * certified, they approve there, and the wallet redirects back with an
- * `AccountProof<DeviceCert>` over that key.
- *
- * ## The credential comes back in the FRAGMENT
- *
- * Same reason the cloud's link grant does — see `link-redirect.ts`. A fragment
- * is not sent to the server, so it lands in nobody's access log, no referrer
- * header and no proxy trace on the way. A query string would put a credential
- * into every log between here and the app's host.
- *
- * ## What the app must check before storing anything
- *
- * A fragment is written by whoever sent the person to this URL, which is not
- * necessarily the wallet. Three things therefore have to be checked locally:
- *
- * - the credential certifies **the key this app asked about** — otherwise the
- *   app stores a credential it cannot sign for, and every warrant it mints is
- *   refused somewhere far from here;
- * - the credential is **internally consistent** — the root signed it, the
- *   account it names is the one that root derives, and its device id was
- *   minted for that account ({@link verifyDeviceCredential});
- * - the account reported beside it is **the account the credential names** —
- *   the app shows that id to a person and keys state by it, so a mismatch is a
- *   credential filed under someone else's name.
- *
- * {@link completeDeviceEnrolment} does all three and throws on any of them,
- * before the caller has anything to store. What none of them establish is that
- * the account is the *person's* — anyone can mint a root offline and certify
- * any public key with it, and a device key is public once enrolled. That is
- * what the state narrows: {@link deviceEnrolmentUrl} remembers each request, and
- * {@link completeDeviceEnrolment} refuses an answer to a request this browser did
- * not start, rather than to a link someone sent.
- */
-import { verifyDeviceCredential, } from '../device-cert/index.js';
-import { beginState, takeState } from './link-state.js';
-/** Query parameters the wallet reads. Mirrors the cloud's `link-account` shape. */
-const DEVICE_PARAM = 'enrol-device';
-const KEM_PARAM = 'enrol-kem';
-const CALLBACK_PARAM = 'callback-url';
-const STATE_PARAM = 'state';
-const PENDING_KEY = 'calimero.device.enrol.pending';
-/**
- * The URL to send a person to.
- *
- * Built rather than documented as a string so the parameter names live in one
- * place: a wallet and an app that disagree about them fail as a blank consent
- * screen, which looks like an outage rather than a contract mismatch.
- *
- * Remembers the request under a fresh state the wallet echoes back, so
- * {@link completeDeviceEnrolment} can match the answer to it.
- */
-export function deviceEnrolmentUrl(options) {
-    assertHex(options.devicePublicKey, 'devicePublicKey');
-    assertHex(options.kemPublicKey, 'kemPublicKey');
-    assertSafeReturnTo(options.returnTo);
-    warnOnForeignCallback(options.returnTo);
-    const url = new URL(options.walletUrl);
-    url.searchParams.set(DEVICE_PARAM, options.devicePublicKey);
-    url.searchParams.set(KEM_PARAM, options.kemPublicKey);
-    url.searchParams.set(CALLBACK_PARAM, options.returnTo);
-    url.searchParams.set(STATE_PARAM, beginState(PENDING_KEY, {}));
-    return url.toString();
-}
-/** Send the person to the wallet to approve this device. Does not return. */
-export function beginDeviceEnrolment(options) {
-    window.location.assign(deviceEnrolmentUrl(options));
-    // `assign` does not stop execution, and a caller that kept going would act on
-    // a page already being replaced.
-    throw new Error('redirecting to the wallet to approve this device');
-}
-/**
- * Read an enrolment out of the current URL fragment, and strip it.
- *
- * Returns `null` on an ordinary page load, so a caller can run it
- * unconditionally at startup. Throws when the person declined, because that is
- * an outcome the app has to show rather than a state to wait in.
- *
- * Nothing is verified here — the shape is separated from the checking so a
- * caller can see what arrived (to log it, or to name the account in a refusal)
- * even when it goes on to be refused. Nothing read out of this belongs in
- * storage until {@link completeDeviceEnrolment} has passed.
- */
-export function readEnrolmentCallback(location = window.location) {
-    const params = new URLSearchParams(location.hash.replace(/^#/, ''));
-    const error = params.get('error');
-    if (error) {
-        takeState(PENDING_KEY, params.get(STATE_PARAM));
-        stripFragment();
-        throw new Error(error === 'denied' || error === 'cancelled'
-            ? 'the device was not approved at the wallet'
-            : `the wallet refused this enrolment: ${error}`);
-    }
-    const credential = params.get('credential');
-    const account = params.get('account');
-    const device = params.get('device');
-    if (!credential || !account || !device)
-        return null;
-    // Consumed once. A credential left in the address bar is replayed by a
-    // reload, ends up in the browser's history and session restore, and is the
-    // one value here worth keeping out of both.
-    stripFragment();
-    const state = params.get('state');
-    return { credential, account, device, ...(state ? { state } : {}) };
-}
-function stripFragment() {
-    if (typeof history === 'undefined' || !history.replaceState)
-        return;
-    history.replaceState(null, '', location.pathname + location.search);
-}
-/**
- * Verify what came back, and refuse loudly rather than returning a half-checked
- * credential.
- *
- * Every throw here is a credential that must not reach storage. The order is
- * deliberate: the cheap local comparisons first, so a fragment aimed at the
- * wrong app is rejected without a signature verification, and the message names
- * what disagreed rather than reporting "invalid credential".
- *
- * The state is spent on the first call, so an answer is accepted at most once.
- */
-export async function completeDeviceEnrolment(options) {
-    if (!takeState(PENDING_KEY, options.state)) {
-        throw new Error('this enrolment answers a request this app did not make - start the ' +
-            'enrolment again from here');
-    }
-    const certificate = await verifyDeviceCredential(options.credential);
-    if (certificate.signPublicKey !== normaliseHex(options.devicePublicKey)) {
-        throw new Error(`this credential certifies device key ${certificate.signPublicKey}, but ` +
-            `this app holds ${normaliseHex(options.devicePublicKey)} — it would ` +
-            'sign with a key the certificate does not cover');
-    }
-    if (options.kemPublicKey !== undefined &&
-        certificate.kemPublicKey !== normaliseHex(options.kemPublicKey)) {
-        throw new Error(`this credential names delivery key ${certificate.kemPublicKey}, not the ` +
-            'one this app asked about — group keys would be sealed to somebody else');
-    }
-    if (certificate.account !== normaliseHex(options.account)) {
-        throw new Error(`the wallet reported account ${normaliseHex(options.account)}, but the ` +
-            `credential names ${certificate.account}`);
-    }
-    if (certificate.device !== normaliseHex(options.device)) {
-        throw new Error(`the wallet reported device ${normaliseHex(options.device)}, but the ` +
-            `credential names ${certificate.device}`);
-    }
-    return {
-        credential: options.credential,
-        account: certificate.account,
-        device: certificate.device,
-        certificate,
-    };
-}
-function assertHex(value, label) {
-    if (!/^[0-9a-f]{64}$/.test(value)) {
-        throw new Error(`${label} must be 64 lowercase hex characters`);
-    }
-}
-function normaliseHex(value) {
-    return value.trim().toLowerCase();
-}
-/**
- * Where a credential may be delivered.
- *
- * `https:` anywhere, `http:` only on loopback. Plain HTTP elsewhere would put
- * the fragment on a page any network position can rewrite, and the fragment is
- * the credential; loopback is exempt because it never leaves the machine and is
- * the only way to develop against a wallet at all.
- *
- * Everything else — `javascript:`, `data:`, a custom app scheme — is refused.
- * The first two are script the wallet would be asked to run; a custom scheme is
- * a legitimate thing to want for a native app, but which installed handler
- * claims it is not something this SDK can check, so it is refused here rather
- * than accepted on trust.
- */
-/**
- * Is the credential coming back to somewhere other than the page that asked?
- *
- * Normally an app enrols its own device key and gets the answer back on its own
- * origin, so the two match. They can legitimately differ — a callback page on a
- * sibling host, an app mid-migration — which is why this is not refused.
- *
- * But it is the shape an abuse would also take: send someone to the real wallet
- * and have the credential delivered elsewhere. Nothing here can tell the two
- * apart, and a client-side check constrains nobody who did not call this
- * function anyway. What it is good for is the honest case — surfacing the
- * mismatch to whoever is building the app, and giving a wallet the same fact to
- * put in front of the person approving.
- *
- * Exported so a wallet can render it, rather than each caller re-deriving it.
- */
-export function callbackIsForeign(returnTo, pageOrigin) {
-    const here = pageOrigin ?? (typeof window === 'undefined' ? undefined : window.location.origin);
-    if (!here)
-        return false;
-    try {
-        return new URL(returnTo).origin !== here;
-    }
-    catch {
-        return false;
-    }
-}
-function warnOnForeignCallback(returnTo) {
-    if (!callbackIsForeign(returnTo))
-        return;
-    // A warning, not a throw: see `callbackIsForeign` for why this is a smell
-    // rather than a verdict.
-    console.warn(`[calimero] enrolling a device but sending the credential to ${new URL(returnTo).origin}, ` +
-        `which is not this page's origin. Legitimate when deliberate; worth a second look otherwise.`);
-}
-function assertSafeReturnTo(returnTo) {
-    let url;
-    try {
-        url = new URL(returnTo);
-    }
-    catch {
-        throw new Error(`returnTo must be an absolute URL, got ${returnTo}`);
-    }
-    const loopback = url.hostname === 'localhost' ||
-        url.hostname === '127.0.0.1' ||
-        url.hostname === '[::1]' ||
-        url.hostname === '::1';
-    if (url.protocol === 'https:')
-        return;
-    if (url.protocol === 'http:' && loopback)
-        return;
-    throw new Error(`returnTo must be https:, or http: on localhost — got ${url.protocol}//${url.hostname}`);
-}

package/dist/cloud/index.d.ts

@@ -1,12 +0,0 @@
-export { CloudClient, admitterAddrsFromNetworkStatus, AccountHaRefusedError, AccountNotLinkedError, AccountLinkedToSeveralUsersError, HaRequestPendingError, UnknownRelayError, RelayNotDialableError, } from './cloud-client.js';
-export type { CloudClientConfig, CloudSession, CloudNamespace, CloudRelay, CloudRelayJoin, CloudAccountRelay, CloudNamespaceNode, CloudNamespaceRouting, CloudMachine, CloudMachineNamespace, CloudLinkedAccount, CloudLinkedAccounts, CloudAccountLink, AccountLinkChallenge, AccountLinkProof, AccountLinkHandoff, AccountLinkCallback, AccountLoginChallenge, AccountLoginProof, EnableHAOptions, DisableHAOptions, EnableHaAsAccountOptions, } from './cloud-client.js';
-export { connectCloud, connectCloudWithAccount } from './connect.js';
-export type { ConnectCloudOptions, ConnectCloudWithAccountOptions, CloudConnection, } from './connect.js';
-export { signRoutingChallenge, routingProofHeaders } from './routing-proof.js';
-export type { RoutingCredential, DiscoveryChallenge, RoutingChallenge, RoutingProofHeaders, } from './routing-proof.js';
-export { cloudLinkUrl, beginCloudLink, readCloudLinkCallback, completeCloudLink, } from './link-redirect.js';
-export type { BeginCloudLinkOptions, CloudLinkCallback, CompleteCloudLinkOptions, } from './link-redirect.js';
-export { deviceEnrolmentUrl, beginDeviceEnrolment, readEnrolmentCallback, completeDeviceEnrolment, callbackIsForeign, } from './enrol-redirect.js';
-export type { DeviceEnrolmentOptions, DeviceEnrolmentCallback, CompleteDeviceEnrolmentOptions, EnrolledDevice, } from './enrol-redirect.js';
-export { signAccountOwnershipClaim, signAccountHaClaim, ACCOUNT_OWNERSHIP_AUDIENCE, ACCOUNT_HA_AUDIENCE, } from './account-ownership.js';
-export type { AccountOwnershipProof, AccountOwnershipClaimInput, AccountHaClaimInput, } from './account-ownership.js';

package/dist/cloud/index.js

@@ -1,10 +0,0 @@
-export { CloudClient, admitterAddrsFromNetworkStatus, AccountHaRefusedError, AccountNotLinkedError, AccountLinkedToSeveralUsersError, HaRequestPendingError, UnknownRelayError, RelayNotDialableError, } from './cloud-client.js';
-export { connectCloud, connectCloudWithAccount } from './connect.js';
-export { signRoutingChallenge, routingProofHeaders } from './routing-proof.js';
-// Linking an account to a cloud login from a browser — the redirect half the
-// cloud's consent screen expects an app to implement.
-export { cloudLinkUrl, beginCloudLink, readCloudLinkCallback, completeCloudLink, } from './link-redirect.js';
-// Getting this app's device key certified by a wallet on another origin — the
-// redirect that keeps the account root out of the app's reach.
-export { deviceEnrolmentUrl, beginDeviceEnrolment, readEnrolmentCallback, completeDeviceEnrolment, callbackIsForeign, } from './enrol-redirect.js';
-export { signAccountOwnershipClaim, signAccountHaClaim, ACCOUNT_OWNERSHIP_AUDIENCE, ACCOUNT_HA_AUDIENCE, } from './account-ownership.js';

package/dist/cloud/link-redirect.d.ts

@@ -1,95 +0,0 @@
-/**
- * Linking an account to a cloud login **from a browser**.
- *
- * The cloud's own accounts screen says it plainly: *"The cloud cannot link an
- * account on your behalf: proving you own it is a signature by the account root
- * key, which the cloud never holds."* So the link needs two things that live in
- * different places — a cloud session, which only Google can mint, and a root
- * signature, which only the holder can make. Neither side can do it alone.
- *
- * The cloud already implements its half: send a person to
- * `?link-account=<id>&challenge=<sha256(verifier)>&callback-url=<url>`, it
- * shows a consent screen and redirects back with a **grant** — that login's
- * sealed consent to link one named account. This module is the missing other
- * half, and it is deliberately small: send them there, then spend what comes
- * back.
- *
- * ## Why a grant rather than a session
- *
- * A grant is spendable only with the account's root and the verifier this
- * browser kept when it began the link. That is what lets the page complete the
- * link while holding **no cloud session at all** - and it is why a wallet
- * should never be handed one. A session token is a credential for everything
- * that login can do; a grant is a credential for exactly one link, to exactly
- * one account, sealed at the moment the person read the id on screen and
- * agreed to it.
- *
- * ## The account id is chosen by us and read by them
- *
- * The cloud seals the account into the grant at consent time, and its own note
- * says why: the server can check that the key which later signs derives that
- * same account, but *"it cannot know whether the person meant this account"*.
- * The consent screen is that check. So show the same id the person will see,
- * before sending them — a wallet that hides it has removed the only safeguard.
- */
-import type { CloudAccountLink } from './cloud-client.js';
-import { type RootSource } from '../account/account.js';
-export interface BeginCloudLinkOptions {
-    /** The account to link — 64 hex. Show this to the person before redirecting. */
-    accountId: string;
-    /**
-     * Where the cloud sends them back. Must be `https:`, or `http:` on localhost.
-     *
-     * The grant returns in the URL **fragment**, which is never sent to a server,
-     * so it does not land in anyone's access log on the way.
-     */
-    returnTo: string;
-    /** The cloud's web origin. Defaults to the hosted one. */
-    cloudWebUrl?: string;
-}
-/**
- * The consent URL to send a person to. Remembers the link, and the verifier its
- * grant will be bound to, so only this browser can match the callback and spend it.
- */
-export declare function cloudLinkUrl(options: BeginCloudLinkOptions): Promise<string>;
-/** Send the person to the cloud to consent. Does not return. */
-export declare function beginCloudLink(options: BeginCloudLinkOptions): Promise<never>;
-/** What came back in the fragment, if anything. */
-export interface CloudLinkCallback {
-    grant: string;
-    /** The account the cloud sealed into the grant. */
-    account: string;
-    /** The cloud login that consented. Show it before spending: anyone holding the consent URL could have answered it. */
-    login: string;
-    /** This browser's secret for the grant, kept from the redirect. Spend it with the grant. */
-    verifier: string;
-}
-/**
- * Read a grant out of the current URL fragment, and strip it.
- *
- * Returns `null` when this is an ordinary page load, so a caller can run it
- * unconditionally at startup. Throws when declined or when this browser did not
- * begin the link.
- */
-export declare function readCloudLinkCallback(location?: {
-    hash: string;
-    search?: string;
-}): CloudLinkCallback | null;
-export interface CompleteCloudLinkOptions extends CloudLinkCallback {
-    /** The account root — a 64-hex secret, or a Signer over a key you cannot read. */
-    root: RootSource;
-    /** The **manager** API base, e.g. `https://manager.cloud.calimero.network`. */
-    cloudBaseUrl?: string;
-    fetch?: typeof fetch;
-}
-/**
- * Spend the grant: sign it with the root and hand it back to the cloud.
- *
- * Anonymous by construction — the client is built with no session, because the
- * whole point is that the page never needed one.
- *
- * @throws if the grant names a different account than the root derives, before
- * anything is sent. The cloud checks this too, but failing here says which two
- * accounts disagreed rather than returning a bare 403.
- */
-export declare function completeCloudLink(options: CompleteCloudLinkOptions): Promise<CloudAccountLink>;

package/dist/cloud/link-redirect.js

@@ -1,121 +0,0 @@
-/**
- * Linking an account to a cloud login **from a browser**.
- *
- * The cloud's own accounts screen says it plainly: *"The cloud cannot link an
- * account on your behalf: proving you own it is a signature by the account root
- * key, which the cloud never holds."* So the link needs two things that live in
- * different places — a cloud session, which only Google can mint, and a root
- * signature, which only the holder can make. Neither side can do it alone.
- *
- * The cloud already implements its half: send a person to
- * `?link-account=<id>&challenge=<sha256(verifier)>&callback-url=<url>`, it
- * shows a consent screen and redirects back with a **grant** — that login's
- * sealed consent to link one named account. This module is the missing other
- * half, and it is deliberately small: send them there, then spend what comes
- * back.
- *
- * ## Why a grant rather than a session
- *
- * A grant is spendable only with the account's root and the verifier this
- * browser kept when it began the link. That is what lets the page complete the
- * link while holding **no cloud session at all** - and it is why a wallet
- * should never be handed one. A session token is a credential for everything
- * that login can do; a grant is a credential for exactly one link, to exactly
- * one account, sealed at the moment the person read the id on screen and
- * agreed to it.
- *
- * ## The account id is chosen by us and read by them
- *
- * The cloud seals the account into the grant at consent time, and its own note
- * says why: the server can check that the key which later signs derives that
- * same account, but *"it cannot know whether the person meant this account"*.
- * The consent screen is that check. So show the same id the person will see,
- * before sending them — a wallet that hides it has removed the only safeguard.
- */
-import { CloudClient } from './cloud-client.js';
-import { resolveRoot } from '../account/account.js';
-import { beginLinkState, linkGrantClaims, takeLinkVerifier, withoutLinkState } from './link-state.js';
-/** Where the consent screen lives. The web app, not the manager API. */
-const DEFAULT_CLOUD_WEB_URL = 'https://cloud.calimero.network';
-/**
- * The consent URL to send a person to. Remembers the link, and the verifier its
- * grant will be bound to, so only this browser can match the callback and spend it.
- */
-export async function cloudLinkUrl(options) {
-    const url = new URL(options.cloudWebUrl ?? DEFAULT_CLOUD_WEB_URL);
-    const { callbackUrl, challenge } = await beginLinkState(options.accountId, options.returnTo);
-    url.searchParams.set('link-account', options.accountId);
-    url.searchParams.set('challenge', challenge);
-    url.searchParams.set('callback-url', callbackUrl);
-    return url.toString();
-}
-/** Send the person to the cloud to consent. Does not return. */
-export async function beginCloudLink(options) {
-    window.location.assign(await cloudLinkUrl(options));
-    // `assign` does not stop execution, and a caller that kept going would act on
-    // a page already being replaced.
-    throw new Error('redirecting to the cloud to authorise this link');
-}
-/**
- * Read a grant out of the current URL fragment, and strip it.
- *
- * Returns `null` when this is an ordinary page load, so a caller can run it
- * unconditionally at startup. Throws when declined or when this browser did not
- * begin the link.
- */
-export function readCloudLinkCallback(location = window.location) {
-    const params = new URLSearchParams(location.hash.replace(/^#/, ''));
-    const error = params.get('error');
-    if (error) {
-        takeLinkVerifier(location.search ?? '', null);
-        stripFragment();
-        throw new Error(error === 'denied'
-            ? 'the account link was declined at the cloud'
-            : `the cloud refused this link: ${error}`);
-    }
-    const grant = params.get('grant');
-    const account = params.get('account');
-    if (!grant || !account)
-        return null;
-    const verifier = takeLinkVerifier(location.search ?? '', account);
-    const claims = linkGrantClaims(grant);
-    if (!verifier || claims?.account !== account) {
-        stripFragment();
-        throw new Error('this account link answers a request this browser did not make - start the link again from here');
-    }
-    // Consumed once. Leaving it in the bar means a reload replays a spent grant
-    // and reports a confusing failure instead of the link that already worked.
-    stripFragment();
-    return { grant, account, login: claims.login, verifier };
-}
-function stripFragment() {
-    if (typeof history === 'undefined' || !history.replaceState)
-        return;
-    history.replaceState(null, '', location.pathname + withoutLinkState(location.search));
-}
-/**
- * Spend the grant: sign it with the root and hand it back to the cloud.
- *
- * Anonymous by construction — the client is built with no session, because the
- * whole point is that the page never needed one.
- *
- * @throws if the grant names a different account than the root derives, before
- * anything is sent. The cloud checks this too, but failing here says which two
- * accounts disagreed rather than returning a bare 403.
- */
-export async function completeCloudLink(options) {
-    const root = await resolveRoot(options.root);
-    if (root.accountId !== options.account) {
-        throw new Error(`this grant is for account ${options.account}, but the root here derives ` +
-            `${root.accountId} — it was minted for a different account`);
-    }
-    const cloud = new CloudClient({
-        cloudBaseUrl: options.cloudBaseUrl,
-        fetch: options.fetch,
-    });
-    return cloud.linkAccountWithGrant({
-        grant: options.grant,
-        verifier: options.verifier,
-        signer: root.signer,
-    });
-}

package/dist/cloud/link-state.d.ts

@@ -1,36 +0,0 @@
-/**
- * Redirects this browser began, so a callback can be matched to one. `localStorage`,
- * not `sessionStorage`: consent opens in a `noopener` tab with empty session storage.
- */
-export declare const ACCOUNT_HEX: RegExp;
-export declare const VERIFIER_HEX: RegExp;
-/** Remember `payload` in the `key` store under a fresh random state, and return the state. */
-export declare function beginState<T extends object>(key: string, payload: T): string;
-/** Removes and returns what `state` was begun with, or null when this browser did not begin it. */
-export declare function takeState<T extends object>(key: string, state: string | null | undefined): T | null;
-/** What a link grant claims, read without its seal, which only the cloud can check. */
-export interface LinkGrantClaims {
-    /** The cloud login that consented. */
-    login: string;
-    account: string;
-    challenge: string;
-}
-/** The challenge a verifier commits to: sha256 of its bytes, hex. */
-export declare function linkChallenge(verifier: string): Promise<string>;
-/**
- * Remember a link for `account` under a fresh verifier. Returns `returnTo`
- * carrying its state, and the challenge to send the cloud in place of the verifier.
- */
-export declare function beginLinkState(account: string, returnTo: string): Promise<{
-    callbackUrl: string;
-    challenge: string;
-}>;
-/**
- * Removes the link a callback answers and returns its verifier, or null when
- * this browser did not begin a link for `account` with this state.
- */
-export declare function takeLinkVerifier(search: string, account: string | null): string | null;
-/** The claims of a link grant, or null when `grant` is not one. */
-export declare function linkGrantClaims(grant: string): LinkGrantClaims | null;
-/** The query with the link state removed, for rewriting the address bar. */
-export declare function withoutLinkState(search: string): string;

package/dist/cloud/link-state.js

@@ -1,104 +0,0 @@
-/**
- * Redirects this browser began, so a callback can be matched to one. `localStorage`,
- * not `sessionStorage`: consent opens in a `noopener` tab with empty session storage.
- */
-import { hex } from "../crypto/internal.js";
-const KEY = "calimero.cloud.link.pending";
-const STATE_PARAM = "link_state";
-const LIFETIME_MS = 10 * 60 * 1000; // a grant lives 5 minutes, plus time to consent
-export const ACCOUNT_HEX = /^[0-9a-f]{64}$/;
-const MAX_PENDING = 20; // bounds storage when a page builds a consent URL on every render
-const VERIFIER_BYTES = 32; // the cloud refuses any other length
-export const VERIFIER_HEX = /^[0-9a-f]{64}$/;
-const LINK_GRANT_USE = "account-link-grant";
-function readPending(key, now) {
-    try {
-        const raw = localStorage.getItem(key);
-        const pending = raw ? JSON.parse(raw) : {};
-        return Object.fromEntries(Object.entries(pending).filter(([, p]) => p && typeof p.expiresAt === "number" && p.expiresAt > now));
-    }
-    catch {
-        return {};
-    }
-}
-function writePending(key, pending) {
-    try {
-        localStorage.setItem(key, JSON.stringify(pending));
-    }
-    catch {
-        // Storage blocked: the redirect cannot be matched later and fails closed.
-    }
-}
-/** Remember `payload` in the `key` store under a fresh random state, and return the state. */
-export function beginState(key, payload) {
-    const now = Date.now();
-    const pending = readPending(key, now);
-    const state = hex(crypto.getRandomValues(new Uint8Array(16)));
-    pending[state] = { ...payload, expiresAt: now + LIFETIME_MS };
-    writePending(key, Object.fromEntries(Object.entries(pending).slice(-MAX_PENDING)));
-    return state;
-}
-/** Removes and returns what `state` was begun with, or null when this browser did not begin it. */
-export function takeState(key, state) {
-    const pending = readPending(key, Date.now());
-    if (!state || !Object.prototype.hasOwnProperty.call(pending, state))
-        return null;
-    const entry = pending[state];
-    delete pending[state];
-    writePending(key, pending);
-    return entry;
-}
-/** The challenge a verifier commits to: sha256 of its bytes, hex. */
-export async function linkChallenge(verifier) {
-    const bytes = Uint8Array.from(verifier.match(/../g) ?? [], (b) => parseInt(b, 16));
-    return hex(new Uint8Array(await crypto.subtle.digest("SHA-256", bytes)));
-}
-/**
- * Remember a link for `account` under a fresh verifier. Returns `returnTo`
- * carrying its state, and the challenge to send the cloud in place of the verifier.
- */
-export async function beginLinkState(account, returnTo) {
-    if (!ACCOUNT_HEX.test(account)) {
-        throw new Error("accountId must be 64 lowercase hex characters");
-    }
-    const url = new URL(returnTo);
-    const verifier = hex(crypto.getRandomValues(new Uint8Array(VERIFIER_BYTES)));
-    const challenge = await linkChallenge(verifier);
-    url.searchParams.set(STATE_PARAM, beginState(KEY, { account, verifier }));
-    return { callbackUrl: url.toString(), challenge };
-}
-/**
- * Removes the link a callback answers and returns its verifier, or null when
- * this browser did not begin a link for `account` with this state.
- */
-export function takeLinkVerifier(search, account) {
-    const pending = takeState(KEY, new URLSearchParams(search).get(STATE_PARAM));
-    if (!pending || pending.account !== account)
-        return null;
-    return typeof pending.verifier === "string" && VERIFIER_HEX.test(pending.verifier)
-        ? pending.verifier
-        : null;
-}
-/** The claims of a link grant, or null when `grant` is not one. */
-export function linkGrantClaims(grant) {
-    try {
-        const body = grant.split(".")[0].replace(/-/g, "+").replace(/_/g, "/");
-        const claims = JSON.parse(new TextDecoder().decode(Uint8Array.from(atob(body), (c) => c.charCodeAt(0))));
-        const { use, sub, acc, chal } = claims;
-        if (use !== LINK_GRANT_USE)
-            return null;
-        if (typeof sub !== "string" || typeof acc !== "string" || typeof chal !== "string")
-            return null;
-        return { login: sub, account: acc, challenge: chal };
-    }
-    catch {
-        return null;
-    }
-}
-/** The query with the link state removed, for rewriting the address bar. */
-export function withoutLinkState(search) {
-    const params = new URLSearchParams(search);
-    params.delete(STATE_PARAM);
-    const rest = params.toString();
-    return rest ? `?${rest}` : "";
-}