@interop/wallet-core 0.1.0

package/dist/space/collections.js

@@ -0,0 +1,65 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The shared wallet Space layout: the collection ids and descriptive specs both
+ * wallet replicas provision, so a credential written by one is found and read by
+ * the other. Both replicas MUST agree on every field here -- `collectionId`
+ * decides where a document lands on the server, `idDerivation` and `mutable`
+ * decide whether it is overwritten in place or only appended, and `encryption` /
+ * `isPublic` decide how it is stored and who can read it. A disagreement splits
+ * the feed into separate or incompatibly-shaped collections that never converge.
+ *
+ * The contacts collections (`contacts`, `contacts-history`) are NOT declared
+ * here: their ids and specs live in `@interop/social-core`
+ * (`CONTACTS_COLLECTION_SPEC` / `CONTACTS_HISTORY_COLLECTION_SPEC`), which apps
+ * import directly. The field vocabulary below mirrors that spec.
+ */
+/** The immutable, content-addressed, EDV-encrypted credential replica. */
+export const PRIVATE_CREDENTIALS_COLLECTION = 'private-credentials';
+/** The plaintext, world-readable copies of publicly shared credentials. */
+export const PUBLIC_CREDENTIALS_COLLECTION = 'public-credentials';
+/** The append-only, EDV-encrypted wallet activity log. */
+export const WALLET_ACTIVITY_COLLECTION = 'wallet-activity';
+/**
+ * The immutable credential replica: each credential stored as an EDV envelope,
+ * addressed by the envelope's content hash, never overwritten, never public.
+ */
+export const PRIVATE_CREDENTIALS_COLLECTION_SPEC = {
+    collectionId: PRIVATE_CREDENTIALS_COLLECTION,
+    idDerivation: 'content',
+    mutable: false,
+    encryption: 'edv',
+    isPublic: false
+};
+/**
+ * The plaintext, world-readable copies of shared credentials, keyed by the
+ * credential's content cid (the same id every replica mints, so a share
+ * converges), granted collection-level world read on the server.
+ */
+export const PUBLIC_CREDENTIALS_COLLECTION_SPEC = {
+    collectionId: PUBLIC_CREDENTIALS_COLLECTION,
+    idDerivation: 'content',
+    mutable: false,
+    encryption: 'plaintext',
+    isPublic: true
+};
+/**
+ * The append-only activity log: each entry stored as an EDV envelope, addressed
+ * by content hash, never overwritten, never public. Shared with the web wallet's
+ * `wallet-activity` collection, so each replica reads the other's entries.
+ */
+export const WALLET_ACTIVITY_COLLECTION_SPEC = {
+    collectionId: WALLET_ACTIVITY_COLLECTION,
+    idDerivation: 'content',
+    mutable: false,
+    encryption: 'edv',
+    isPublic: false
+};
+/** The wallet Space's own (non-contacts) collection specs, in provision order. */
+export const WALLET_SPACE_COLLECTION_SPECS = [
+    PRIVATE_CREDENTIALS_COLLECTION_SPEC,
+    PUBLIC_CREDENTIALS_COLLECTION_SPEC,
+    WALLET_ACTIVITY_COLLECTION_SPEC
+];
+//# sourceMappingURL=collections.js.map

package/dist/space/collections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collections.js","sourceRoot":"","sources":["../../src/space/collections.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;GAaG;AAEH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,8BAA8B,GAAG,qBAAqB,CAAA;AACnE,2EAA2E;AAC3E,MAAM,CAAC,MAAM,6BAA6B,GAAG,oBAAoB,CAAA;AACjE,0DAA0D;AAC1D,MAAM,CAAC,MAAM,0BAA0B,GAAG,iBAAiB,CAAA;AAyB3D;;;GAGG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAwB;IACtE,YAAY,EAAE,8BAA8B;IAC5C,YAAY,EAAE,SAAS;IACvB,OAAO,EAAE,KAAK;IACd,UAAU,EAAE,KAAK;IACjB,QAAQ,EAAE,KAAK;CAChB,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAwB;IACrE,YAAY,EAAE,6BAA6B;IAC3C,YAAY,EAAE,SAAS;IACvB,OAAO,EAAE,KAAK;IACd,UAAU,EAAE,WAAW;IACvB,QAAQ,EAAE,IAAI;CACf,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAwB;IAClE,YAAY,EAAE,0BAA0B;IACxC,YAAY,EAAE,SAAS;IACvB,OAAO,EAAE,KAAK;IACd,UAAU,EAAE,KAAK;IACjB,QAAQ,EAAE,KAAK;CAChB,CAAA;AAED,kFAAkF;AAClF,MAAM,CAAC,MAAM,6BAA6B,GAA0B;IAClE,mCAAmC;IACnC,kCAAkC;IAClC,+BAA+B;CAChC,CAAA"}

package/dist/space/errors.d.ts

@@ -0,0 +1,14 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * A user-facing error whose `message` is safe to show verbatim. Carries the name
+ * `'HumanReadableError'` so an app that classifies errors by `name` (rather than
+ * by `instanceof`, which fails across module realms) treats a wallet-core error
+ * the same as its own. Thrown by `parseWasLinkPayload` for every malformed /
+ * wrong-version / non-link input.
+ */
+export declare class HumanReadableError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/space/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/space/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;GAMG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAK5B"}

package/dist/space/errors.js

@@ -0,0 +1,18 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * A user-facing error whose `message` is safe to show verbatim. Carries the name
+ * `'HumanReadableError'` so an app that classifies errors by `name` (rather than
+ * by `instanceof`, which fails across module realms) treats a wallet-core error
+ * the same as its own. Thrown by `parseWasLinkPayload` for every malformed /
+ * wrong-version / non-link input.
+ */
+export class HumanReadableError extends Error {
+    constructor(message) {
+        super(message);
+        this.message = message;
+        this.name = 'HumanReadableError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/space/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/space/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;GAMG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;QACtB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;IAClC,CAAC;CACF"}

package/dist/space/index.d.ts

@@ -0,0 +1,26 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `@interop/wallet-core/space` subpath: the wallet Space layout contract two
+ * WAS-enabled wallet apps share.
+ *
+ * - The shared collection ids and descriptive specs (`private-credentials`,
+ *   `public-credentials`, `wallet-activity`). The contacts collections stay in
+ *   `@interop/social-core`.
+ * - The `wallet-activity` wire shape (`WalletActivity`) and the pure
+ *   `addHistory*` payload builders.
+ * - `publicCredentialUrl`, the world-readable shared-credential URL both
+ *   replicas derive identically.
+ * - The `was-link` QR hand-off contract (`buildWasLinkPayload` /
+ *   `parseWasLinkPayload` / `encodeWasLinkSecret`).
+ */
+export { PRIVATE_CREDENTIALS_COLLECTION, PUBLIC_CREDENTIALS_COLLECTION, WALLET_ACTIVITY_COLLECTION, PRIVATE_CREDENTIALS_COLLECTION_SPEC, PUBLIC_CREDENTIALS_COLLECTION_SPEC, WALLET_ACTIVITY_COLLECTION_SPEC, WALLET_SPACE_COLLECTION_SPECS } from './collections.js';
+export type { SpaceCollectionSpec } from './collections.js';
+export { ACTIVITY_TYPE, addHistoryNewAccount, addHistorySpaceCreated, addHistoryCredentialCreated, addHistoryCredentialDeleted, addHistoryCredentialShared, addHistoryCredentialUnshared, addHistoryLogin, addHistoryAppRevoke } from './activity.js';
+export type { WalletActivity, ActivityGrant } from './activity.js';
+export { publicCredentialUrl } from './publicLink.js';
+export { encodeWasLinkSecret, buildWasLinkPayload, parseWasLinkPayload } from './wasLink.js';
+export type { WasLinkPayload } from './wasLink.js';
+export { HumanReadableError } from './errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/space/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/space/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;GAaG;AACH,OAAO,EACL,8BAA8B,EAC9B,6BAA6B,EAC7B,0BAA0B,EAC1B,mCAAmC,EACnC,kCAAkC,EAClC,+BAA+B,EAC/B,6BAA6B,EAC9B,MAAM,kBAAkB,CAAA;AACzB,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAE3D,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,sBAAsB,EACtB,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAC1B,4BAA4B,EAC5B,eAAe,EACf,mBAAmB,EACpB,MAAM,eAAe,CAAA;AACtB,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAElE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAErD,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAElD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA"}

package/dist/space/index.js

@@ -0,0 +1,23 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `@interop/wallet-core/space` subpath: the wallet Space layout contract two
+ * WAS-enabled wallet apps share.
+ *
+ * - The shared collection ids and descriptive specs (`private-credentials`,
+ *   `public-credentials`, `wallet-activity`). The contacts collections stay in
+ *   `@interop/social-core`.
+ * - The `wallet-activity` wire shape (`WalletActivity`) and the pure
+ *   `addHistory*` payload builders.
+ * - `publicCredentialUrl`, the world-readable shared-credential URL both
+ *   replicas derive identically.
+ * - The `was-link` QR hand-off contract (`buildWasLinkPayload` /
+ *   `parseWasLinkPayload` / `encodeWasLinkSecret`).
+ */
+export { PRIVATE_CREDENTIALS_COLLECTION, PUBLIC_CREDENTIALS_COLLECTION, WALLET_ACTIVITY_COLLECTION, PRIVATE_CREDENTIALS_COLLECTION_SPEC, PUBLIC_CREDENTIALS_COLLECTION_SPEC, WALLET_ACTIVITY_COLLECTION_SPEC, WALLET_SPACE_COLLECTION_SPECS } from './collections.js';
+export { ACTIVITY_TYPE, addHistoryNewAccount, addHistorySpaceCreated, addHistoryCredentialCreated, addHistoryCredentialDeleted, addHistoryCredentialShared, addHistoryCredentialUnshared, addHistoryLogin, addHistoryAppRevoke } from './activity.js';
+export { publicCredentialUrl } from './publicLink.js';
+export { encodeWasLinkSecret, buildWasLinkPayload, parseWasLinkPayload } from './wasLink.js';
+export { HumanReadableError } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/space/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/space/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;GAaG;AACH,OAAO,EACL,8BAA8B,EAC9B,6BAA6B,EAC7B,0BAA0B,EAC1B,mCAAmC,EACnC,kCAAkC,EAClC,+BAA+B,EAC/B,6BAA6B,EAC9B,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,sBAAsB,EACtB,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAC1B,4BAA4B,EAC5B,eAAe,EACf,mBAAmB,EACpB,MAAM,eAAe,CAAA;AAGtB,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAErD,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,cAAc,CAAA;AAGrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA"}

package/dist/space/publicLink.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The absolute, world-readable URL of a credential's shared copy:
+ * `{serverUrl}/space/{spaceId}/public-credentials/{cid}`. Takes the server URL,
+ * Space id, and credential cid as arguments, with no dependency on app config.
+ *
+ * @param options {object}
+ * @param options.serverUrl {string}   the WAS storage server base URL
+ * @param options.spaceId {string}   the profile's WAS Space id
+ * @param options.cid {string}   the credential's content cid
+ * @returns {string}
+ */
+export declare function publicCredentialUrl({ serverUrl, spaceId, cid }: {
+    serverUrl: string;
+    spaceId: string;
+    cid: string;
+}): string;
+//# sourceMappingURL=publicLink.d.ts.map

package/dist/space/publicLink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publicLink.d.ts","sourceRoot":"","sources":["../../src/space/publicLink.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,SAAS,EACT,OAAO,EACP,GAAG,EACJ,EAAE;IACD,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;CACZ,GAAG,MAAM,CAKT"}

package/dist/space/publicLink.js

@@ -0,0 +1,27 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * Public-credential URL derivation. Sharing a credential writes a plaintext copy
+ * into the profile's `public-credentials` collection, keyed by the credential's
+ * content cid; once replication mirrors it to the profile's WAS Space it
+ * resolves at the URL below. Both wallet replicas build the identical URL for a
+ * given `(serverUrl, spaceId, cid)`, so a link handed out by one resolves the
+ * copy replicated by the other.
+ */
+import { PUBLIC_CREDENTIALS_COLLECTION } from './collections.js';
+/**
+ * The absolute, world-readable URL of a credential's shared copy:
+ * `{serverUrl}/space/{spaceId}/public-credentials/{cid}`. Takes the server URL,
+ * Space id, and credential cid as arguments, with no dependency on app config.
+ *
+ * @param options {object}
+ * @param options.serverUrl {string}   the WAS storage server base URL
+ * @param options.spaceId {string}   the profile's WAS Space id
+ * @param options.cid {string}   the credential's content cid
+ * @returns {string}
+ */
+export function publicCredentialUrl({ serverUrl, spaceId, cid }) {
+    return new URL(`/space/${spaceId}/${PUBLIC_CREDENTIALS_COLLECTION}/${cid}`, serverUrl).toString();
+}
+//# sourceMappingURL=publicLink.js.map

package/dist/space/publicLink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publicLink.js","sourceRoot":"","sources":["../../src/space/publicLink.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;GAOG;AACH,OAAO,EAAE,6BAA6B,EAAE,MAAM,kBAAkB,CAAA;AAEhE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAClC,SAAS,EACT,OAAO,EACP,GAAG,EAKJ;IACC,OAAO,IAAI,GAAG,CACZ,UAAU,OAAO,IAAI,6BAA6B,IAAI,GAAG,EAAE,EAC3D,SAAS,CACV,CAAC,QAAQ,EAAE,CAAA;AACd,CAAC"}

package/dist/space/wasLink.d.ts

@@ -0,0 +1,37 @@
+/** The decoded link: the WAS server plus the controller secret AS A STRING. */
+export interface WasLinkPayload {
+    serverUrl: string;
+    /** The controller secret (already decoded back to the passphrase string). */
+    secret: string;
+}
+/**
+ * Encodes a passphrase into the payload's `secret` field: `base64url(utf8(...))`,
+ * no padding.
+ *
+ * @param passphrase {string}
+ * @returns {string}
+ */
+export declare function encodeWasLinkSecret(passphrase: string): string;
+/**
+ * Builds the full `was-link` payload string a QR encodes.
+ *
+ * @param options {object}
+ * @param options.serverUrl {string}
+ * @param options.passphrase {string}
+ * @returns {string}
+ */
+export declare function buildWasLinkPayload({ serverUrl, passphrase }: {
+    serverUrl: string;
+    passphrase: string;
+}): string;
+/**
+ * Parses and validates a scanned payload, returning the server URL and the
+ * decoded string secret. Throws {@link HumanReadableError} for anything that is
+ * not a valid current-version `was-link` payload (so the scanner shows a clean
+ * message rather than mis-handling an unrelated QR).
+ *
+ * @param raw {string}   the raw scanned code value
+ * @returns {WasLinkPayload}
+ */
+export declare function parseWasLinkPayload(raw: string): WasLinkPayload;
+//# sourceMappingURL=wasLink.d.ts.map

package/dist/space/wasLink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasLink.d.ts","sourceRoot":"","sources":["../../src/space/wasLink.ts"],"names":[],"mappings":"AAgBA,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAA;IACjB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAA;CACf;AAyCD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,SAAS,EACT,UAAU,EACX,EAAE;IACD,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;CACnB,GAAG,MAAM,CAOT;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAyC/D"}

package/dist/space/wasLink.js

@@ -0,0 +1,123 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `was-link` QR hand-off payload -- the "Connect mobile wallet" flow where
+ * the web wallet displays a QR that carries an account's controller secret and
+ * the mobile wallet scans it.
+ *
+ * The payload is a NON-URL JSON blob (deliberately not a link, so the OS camera
+ * app / deep-link handling never routes it and it cannot leak into browser
+ * history or link-preview fetchers). It is accepted only by the in-app scanner.
+ * Shape: `{ v: 1, t: 'was-link', serverUrl, secret: base64url(utf8(passphrase)) }`.
+ */
+import { base64urlnopad } from '@scure/base';
+import { HumanReadableError } from './errors.js';
+const NOT_A_LINK = 'This QR code is not a wallet connection code.';
+const BAD_SERVER = 'Connection code points at an insecure or invalid server and was rejected.';
+/** Strips optional base64 padding so the no-pad decoder accepts either form. */
+function stripPadding(value) {
+    return value.replace(/=+$/, '');
+}
+/**
+ * Validates the scanned `serverUrl` before the wallet ever signs a request to
+ * it. The code carries the controller secret in the clear, so a bad `serverUrl`
+ * would let a crafted QR aim capability-signed requests (and the secret) at an
+ * attacker-controlled or cleartext host. Requires a parseable `https:` URL;
+ * plain `http:` is allowed ONLY for loopback dev hosts.
+ *
+ * This is a scheme/host rule, not an allowlist: the payload carries its own
+ * `serverUrl`, and there is no app-configured set of permitted servers to inject
+ * -- a connection code names the storage server the user is joining. If a
+ * consuming app later needs to constrain the host further, that check belongs at
+ * the call site, on the returned {@link WasLinkPayload.serverUrl}.
+ */
+function assertValidServerUrl(serverUrl) {
+    let url;
+    try {
+        url = new URL(serverUrl);
+    }
+    catch {
+        throw new HumanReadableError(BAD_SERVER);
+    }
+    const isLoopback = url.hostname === 'localhost' ||
+        url.hostname === '127.0.0.1' ||
+        url.hostname === '::1';
+    if (url.protocol === 'https:' || (url.protocol === 'http:' && isLoopback)) {
+        return;
+    }
+    throw new HumanReadableError(BAD_SERVER);
+}
+/**
+ * Encodes a passphrase into the payload's `secret` field: `base64url(utf8(...))`,
+ * no padding.
+ *
+ * @param passphrase {string}
+ * @returns {string}
+ */
+export function encodeWasLinkSecret(passphrase) {
+    return base64urlnopad.encode(new TextEncoder().encode(passphrase));
+}
+/**
+ * Builds the full `was-link` payload string a QR encodes.
+ *
+ * @param options {object}
+ * @param options.serverUrl {string}
+ * @param options.passphrase {string}
+ * @returns {string}
+ */
+export function buildWasLinkPayload({ serverUrl, passphrase }) {
+    return JSON.stringify({
+        v: 1,
+        t: 'was-link',
+        serverUrl,
+        secret: encodeWasLinkSecret(passphrase)
+    });
+}
+/**
+ * Parses and validates a scanned payload, returning the server URL and the
+ * decoded string secret. Throws {@link HumanReadableError} for anything that is
+ * not a valid current-version `was-link` payload (so the scanner shows a clean
+ * message rather than mis-handling an unrelated QR).
+ *
+ * @param raw {string}   the raw scanned code value
+ * @returns {WasLinkPayload}
+ */
+export function parseWasLinkPayload(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new HumanReadableError(NOT_A_LINK);
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new HumanReadableError(NOT_A_LINK);
+    }
+    const { v, t, serverUrl, secret } = parsed;
+    if (t !== 'was-link') {
+        throw new HumanReadableError(NOT_A_LINK);
+    }
+    if (v !== 1) {
+        throw new HumanReadableError('This connection code is from a newer app version. Please update.');
+    }
+    if (typeof serverUrl !== 'string' || serverUrl.length === 0) {
+        throw new HumanReadableError('Connection code is missing its server.');
+    }
+    assertValidServerUrl(serverUrl);
+    if (typeof secret !== 'string' || secret.length === 0) {
+        throw new HumanReadableError('Connection code is missing its secret.');
+    }
+    let secretText;
+    try {
+        secretText = new TextDecoder().decode(base64urlnopad.decode(stripPadding(secret)));
+    }
+    catch {
+        throw new HumanReadableError('Connection code has a malformed secret.');
+    }
+    if (secretText.length === 0) {
+        throw new HumanReadableError('Connection code has an empty secret.');
+    }
+    return { serverUrl, secret: secretText };
+}
+//# sourceMappingURL=wasLink.js.map

package/dist/space/wasLink.js.map

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

package/dist/sync/collections.d.ts

@@ -0,0 +1,61 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The generic per-collection spec SHAPE the replication engine + store drive one
+ * feed with. It bundles everything a feed needs: its id and id-derivation model,
+ * its plaintext-projection transactional writers, its lazy-migration sweep, the
+ * read-model refresh to fire after a pull, and (for a mutable collection) its
+ * 412 last-write-wins policy.
+ *
+ * Only the SHAPE lives here. The concrete registry -- which collections a given
+ * app replicates and how each writer touches the app's own store -- stays
+ * app-side, because the writers bind to the app's transaction handle and its
+ * read-model refresh mechanism. The spec is parameterized over those two so a
+ * SQLite-backed replica and a future RxDB adapter can both implement it without
+ * this module importing either store:
+ *
+ * - `Tx` is the store's transaction handle passed to `applyUpsertTx` /
+ *   `applyDeleteTx` (a SQLite database instance in the mobile store; whatever an
+ *   RxDB writer needs in the browser store). It replaces the mobile store's
+ *   concrete `SQLiteDatabase` leak with a type parameter.
+ * - `RefreshContext` is whatever `onPullApplied` needs to trigger a read-model
+ *   refresh (a Redux dispatch in one app, a store handle or `void` in another).
+ */
+import type { DocCipher, Json, ResolveConflict, SyncStore, WasSyncPort } from './types.js';
+/**
+ * One synced collection's full behavior. `applyUpsertTx` / `applyDeleteTx` are
+ * the store's plaintext-projection writers, invoked inside the store's pull
+ * transaction with the decrypted payload; `migrate` is the unlinked-row sweep;
+ * `makeResolveConflict` is present only for a mutable (LWW) collection, absent
+ * for insert-only content-addressed collections whose push settlement covers
+ * every 412.
+ *
+ * `encryption` selects the doc cipher and the server-side collection marker:
+ * `'edv'` (the default) envelopes every doc, `'plaintext'` ships it verbatim;
+ * `isPublic` grants collection-level world read on the server. Both replicas
+ * MUST agree on `collectionId` / `idDerivation` / `encryption` / `isPublic` for
+ * a collection, or their writes land in separate or differently-shaped
+ * collections and never converge.
+ */
+export interface SyncedCollectionSpec<Tx = unknown, RefreshContext = void> {
+    collectionId: string;
+    idDerivation: 'content' | 'random';
+    encryption?: 'edv' | 'plaintext';
+    isPublic?: boolean;
+    applyUpsertTx: (tx: Tx, profileRecordId: string, syncId: string, payload: Json) => Promise<void>;
+    applyDeleteTx: (tx: Tx, profileRecordId: string, syncId: string) => Promise<void>;
+    onPullApplied: (context: RefreshContext) => void;
+    migrate: (options: {
+        profileRecordId: string;
+        cipher: DocCipher;
+        signal?: AbortSignal;
+    }) => Promise<void>;
+    makeResolveConflict?: (options: {
+        profileRecordId: string;
+        cipher: DocCipher;
+        port: WasSyncPort;
+        store: SyncStore;
+    }) => ResolveConflict;
+}
+//# sourceMappingURL=collections.d.ts.map

package/dist/sync/collections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collections.d.ts","sourceRoot":"","sources":["../../src/sync/collections.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EACV,SAAS,EACT,IAAI,EACJ,eAAe,EACf,SAAS,EACT,WAAW,EACZ,MAAM,YAAY,CAAA;AAEnB;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,oBAAoB,CAAC,EAAE,GAAG,OAAO,EAAE,cAAc,GAAG,IAAI;IACvE,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,SAAS,GAAG,QAAQ,CAAA;IAClC,UAAU,CAAC,EAAE,KAAK,GAAG,WAAW,CAAA;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,aAAa,EAAE,CACb,EAAE,EAAE,EAAE,EACN,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,IAAI,KACV,OAAO,CAAC,IAAI,CAAC,CAAA;IAClB,aAAa,EAAE,CACb,EAAE,EAAE,EAAE,EACN,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,MAAM,KACX,OAAO,CAAC,IAAI,CAAC,CAAA;IAClB,aAAa,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAA;IAChD,OAAO,EAAE,CAAC,OAAO,EAAE;QACjB,eAAe,EAAE,MAAM,CAAA;QACvB,MAAM,EAAE,SAAS,CAAA;QACjB,MAAM,CAAC,EAAE,WAAW,CAAA;KACrB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnB,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE;QAC9B,eAAe,EAAE,MAAM,CAAA;QACvB,MAAM,EAAE,SAAS,CAAA;QACjB,IAAI,EAAE,WAAW,CAAA;QACjB,KAAK,EAAE,SAAS,CAAA;KACjB,KAAK,eAAe,CAAA;CACtB"}

package/dist/sync/collections.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=collections.js.map

package/dist/sync/collections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collections.js","sourceRoot":"","sources":["../../src/sync/collections.ts"],"names":[],"mappings":""}

package/dist/sync/engine.d.ts

@@ -0,0 +1,112 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * `SyncEngine` -- drives one `(replica, collection)` feed through the pull/push
+ * cycle. Single-flight (concurrent `sync()` calls coalesce and set a rerun
+ * flag), migrate-once (the initial pull-before-migrate ordering that keeps
+ * envelope minting from creating server-side duplicates), and self-healing via
+ * exponential backoff + jitter on failure.
+ *
+ * All side effects are injected ({@link SyncEngineDeps}) so the engine runs
+ * anywhere -- browser, Node, or React Native -- with a fake port, an in-memory
+ * store, and a non-firing scheduler. The consuming app wires the real port,
+ * DocCipher, provisioning, and lazy migration.
+ */
+import type { Json, ResolveConflict, SyncStore, WasSyncPort } from './types.js';
+/** Per-feed replication status, surfaced to the app's state layer. */
+export type SyncStatus = 'idle' | 'syncing' | 'synced' | 'error';
+/**
+ * Everything the engine needs, injected. The pure protocol ({@link WasSyncPort},
+ * {@link SyncStore}) plus the app-supplied seams: provisioning, the
+ * migrated/last-synced stamps, decryption, and status/refetch callbacks. The
+ * `schedule` / `random` seams make backoff deterministic under test.
+ */
+export interface SyncEngineDeps {
+    port: WasSyncPort;
+    store: SyncStore;
+    /** Decrypts a pulled body to its plaintext payload (DocCipher). */
+    decryptDoc: (envelope: Json) => Promise<Json>;
+    /**
+     * The 412 policy for a mutable (LWW) collection. Absent for insert-only
+     * content-addressed collections, whose built-in push settlement covers every
+     * conflict.
+     */
+    resolveConflict?: ResolveConflict;
+    batchSize?: number;
+    /** Idempotent space + collection provisioning. */
+    ensureProvisioned: () => Promise<void>;
+    /** Has this feed's lazy migration already run (per-collection milestone)? */
+    isMigrated: () => Promise<boolean>;
+    /** Mint bodies for this feed's still-unlinked local rows. */
+    runLazyMigration: (signal: AbortSignal) => Promise<void>;
+    /** Record this feed's migrated milestone after a successful first migration. */
+    stampMigrated: () => Promise<void>;
+    /** Stamp the replica's last-synced time after a successful cycle. */
+    stampLastSynced: () => Promise<void>;
+    /** Called on every status transition (drives the app's state layer). */
+    onStatusChange?: (status: SyncStatus) => void;
+    /** Called after a pull that applied >= 1 document (triggers the refetch). */
+    onPullApplied?: () => void;
+    backoff?: {
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+    };
+    /** Schedules a retry; returns a canceller. Defaults to setTimeout. */
+    schedule?: (fn: () => void, delayMs: number) => () => void;
+    /** Jitter source in [0, 1). Defaults to Math.random. */
+    random?: () => number;
+}
+export declare class SyncEngine {
+    private readonly deps;
+    status: SyncStatus;
+    private readonly batchSize;
+    private readonly baseDelayMs;
+    private readonly maxDelayMs;
+    private readonly schedule;
+    private readonly random;
+    private running;
+    private rerunRequested;
+    private stopped;
+    private failureCount;
+    private currentRun;
+    private abortController;
+    private cancelRetry;
+    constructor(deps: SyncEngineDeps);
+    /**
+     * Requests a sync. Single-flight: if a cycle is in flight this only flags a
+     * rerun (so writes that land mid-cycle are not lost) and resolves with the
+     * in-flight run; otherwise it starts a fresh run. Never rejects -- failures
+     * settle into `status = 'error'` plus a scheduled backoff retry, per the
+     * local-first invariant (sync must never surface as a rejected write).
+     *
+     * @returns {Promise<void>}
+     */
+    sync(): Promise<void>;
+    /**
+     * Stops the engine: aborts any in-flight cycle (the injected signal unwinds
+     * pull/push between pages/rows), cancels a pending retry, and resets to idle.
+     * The caller drops the cached agents/ciphers so key material does not outlive
+     * the unlocked session.
+     */
+    stop(): void;
+    private run;
+    /**
+     * One full replication cycle. On the very first run (never migrated) it pulls
+     * before the sweep so existing local rows hash-link to any bodies already on
+     * the server -- the sweep then only encrypts genuinely-new records
+     * (re-encrypting an existing one would mint a different content id and leave a
+     * permanent server duplicate). The unlinked-record sweep (`runLazyMigration`)
+     * runs on EVERY cycle, not just the first, so records that enter the replica
+     * outside the synced write path -- an import, or a write whose minting failed
+     * and fell back to a plain insert -- are still picked up and pushed (it is a
+     * cheap no-op when there are none). Steady state is sweep-then-push-then-pull:
+     * our own writes echo back in the same cycle's pull, idempotently.
+     */
+    private runCycle;
+    private pull;
+    private scheduleRetry;
+    private clearRetry;
+    private setStatus;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/sync/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/sync/engine.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAI/E,sEAAsE;AACtE,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAA;AAMhE;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,CAAA;IACjB,KAAK,EAAE,SAAS,CAAA;IAChB,mEAAmE;IACnE,UAAU,EAAE,CAAC,QAAQ,EAAE,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7C;;;;OAIG;IACH,eAAe,CAAC,EAAE,eAAe,CAAA;IACjC,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB,kDAAkD;IAClD,iBAAiB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACtC,6EAA6E;IAC7E,UAAU,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IAClC,6DAA6D;IAC7D,gBAAgB,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACxD,gFAAgF;IAChF,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,qEAAqE;IACrE,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAEpC,wEAAwE;IACxE,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAA;IAC7C,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,IAAI,CAAA;IAE1B,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACvD,sEAAsE;IACtE,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,IAAI,CAAA;IAC1D,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,MAAM,CAAA;CACtB;AAOD,qBAAa,UAAU;IAiBT,OAAO,CAAC,QAAQ,CAAC,IAAI;IAhBjC,MAAM,EAAE,UAAU,CAAS;IAE3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiD;IAC1E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IAErC,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,cAAc,CAAQ;IAC9B,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,YAAY,CAAI;IACxB,OAAO,CAAC,UAAU,CAA6B;IAC/C,OAAO,CAAC,eAAe,CAA+B;IACtD,OAAO,CAAC,WAAW,CAA4B;gBAElB,IAAI,EAAE,cAAc;IAQjD;;;;;;;;OAQG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAYrB;;;;;OAKG;IACH,IAAI,IAAI,IAAI;YAOE,GAAG;IA8BjB;;;;;;;;;;;OAWG;YACW,QAAQ;YAoDR,IAAI;IAWlB,OAAO,CAAC,aAAa;IAerB,OAAO,CAAC,UAAU;IAOlB,OAAO,CAAC,SAAS;CAOlB"}