@oxy.so/core 1.18.0 → 3.0.0

package/dist/esm/mixins/OxyServices.chains.js

@@ -1,70 +0,0 @@
-/**
- * Chains — the shared record log every Oxy app reads and writes.
- *
- * A person has ONE chain. An app appends its own records to it and projects its
- * feeds from what it reads back, instead of keeping a private copy of the same
- * person's activity. This mixin is the client half of `/chains` in oxy-api, and
- * it exists so that adopting the chain costs an app no HTTP of its own — the
- * whole point of the shared substrate is that the second app writes less code
- * than the first, not the same amount in a different file.
- *
- * ## Both calls are SERVICE-authenticated
- *
- * They go through `makeServiceRequest`, so they only work on a backend that has
- * called `configureServiceAuth()`. That is not an accident of implementation: an
- * append writes to someone else's chain and a read spans many subjects, so
- * neither belongs in a browser holding a user session. A frontend that needs
- * this asks its own backend.
- *
- * The authority is checked server-side and cannot be talked out of from here:
- * `chains:write` plus the application's own `chainNamespaces` for an append,
- * `chains:read` plus the public-collection policy for a read. A call that
- * violates either gets a 403 or an empty page — this client adds no
- * pre-validation that could drift from the server's answer.
- */
-export function OxyServicesChainsMixin(Base) {
-    return class extends Base {
-        constructor(...args) {
-            super(...args);
-        }
-        /**
-         * Append a record to `oxyUserId`'s chain under `collection`/`rkey`.
-         *
-         * Oxy issues and signs it; the calling app never holds a chain signing key.
-         * `rkey` is the app's own id for the thing — reusing it later supersedes the
-         * earlier record for that key, which is how an edit works.
-         *
-         * Requires the `chains:write` scope AND `collection` falling under one of
-         * this application's granted `chainNamespaces`. Both are enforced by the
-         * server; a violation throws with a 403.
-         */
-        async appendChainRecord(params) {
-            return this.makeServiceRequest('POST', '/chains/records', params);
-        }
-        /**
-         * Records published by any of `oxyUserIds` under any of `collections`,
-         * oldest first — the read a cross-app feed is projected from.
-         *
-         * Only collections Oxy declares PUBLIC come back, whatever is asked for; a
-         * private one yields nothing rather than an error.
-         *
-         * **Re-poll from slightly BEFORE your last cursor and dedupe by
-         * `recordId`.** The chain's pagination axis is a transaction-start
-         * timestamp, so a record can commit behind a cursor that already passed it.
-         * Re-delivering one costs bytes; skipping one costs a record that never
-         * appears. Projections are expected to be idempotent for exactly this
-         * reason.
-         */
-        async readChainRecords(params) {
-            const query = new URLSearchParams({
-                authors: params.oxyUserIds.join(','),
-                collections: params.collections.join(','),
-            });
-            if (params.since)
-                query.set('since', params.since);
-            if (params.limit !== undefined)
-                query.set('limit', String(params.limit));
-            return this.makeServiceRequest('GET', `/chains/records?${query.toString()}`);
-        }
-    };
-}

package/dist/esm/mixins/OxyServices.civic.js

@@ -1,605 +0,0 @@
-import { canonicalize, verifySignature } from '@oxy.so/protocol';
-import { SignatureService } from '../crypto/signatureService.js';
-import { buildUserDid } from './OxyServices.identity.js';
-import { CACHE_TIMES } from './mixinHelpers.js';
-/**
- * Validity window of a real-life-attestation QR (`oxycommons://attest?…exp=…`),
- * matching the server's `REAL_LIFE_NONCE_MAX_AGE_MS` ceiling: the QR must be
- * scanned and submitted within this window. The server is authoritative on
- * freshness; this is the client-issued `exp`.
- */
-const ATTEST_QR_TTL_MS = 10 * 60 * 1000;
-/** AtProto-style collection for a real-life counterparty attestation record. */
-const ATTEST_COLLECTION = 'app.oxy.attestation';
-/** AtProto-style collection for a validator's signed verdict record. */
-const VALIDATION_COLLECTION = 'app.oxy.validation';
-/** AtProto-style collection for a personhood vouch record. */
-const VOUCH_COLLECTION = 'app.oxy.vouch';
-/**
- * AtProto-style collection (NSID) for a verifiable credential record — matches
- * the server's `CREDENTIAL_COLLECTION`. Each credential is its own chain entry,
- * so the per-credential `rkey` MUST be unique (a fresh nonce), unlike the
- * one-per-subject vouch keyed on the subject DID.
- */
-const CREDENTIAL_COLLECTION = 'app.oxy.credential';
-/**
- * The W3C base VC type (`CREDENTIAL_BASE_TYPE` on the server) that MUST be
- * present in every credential's `types`. The client prepends it when the caller
- * omits it; the server rejects a credential record lacking it (`missing_base_type`).
- */
-const CREDENTIAL_BASE_TYPE = 'VerifiableCredential';
-/**
- * Cache-key prefix of every credential read — the holder list
- * (`GET /civic/credentials/:holderUserId`) and the by-record verify
- * (`GET /civic/credentials/by-record/:recordId/verify`) both start with it.
- * Swept after an issue / revoke so a re-read reflects the new credential set /
- * status instead of a stale cached one. The identity tag is a key SUFFIX, so
- * this prefix invalidates the resource for every cached identity.
- */
-const CREDENTIAL_CACHE_PREFIX = 'GET:/civic/credentials/';
-/**
- * Cache-key prefix of every personhood-status read (`GET /civic/personhood/:userId`).
- * Swept after a vouch / withdraw so a re-read reflects the recomputed snapshot
- * instead of a stale cached one. The identity tag is a key SUFFIX, so this
- * prefix invalidates the resource for every cached identity.
- */
-const PERSONHOOD_CACHE_PREFIX = 'GET:/civic/personhood/';
-/**
- * Cache-key prefix of the current user's `GET /users/me`. Swept after a vouch /
- * withdraw because a subject crossing the personhood threshold flips their
- * mirrored `User.verified` flag.
- */
-const USERS_ME_CACHE_PREFIX = 'GET:/users/me';
-/** URI scheme/host that introduces a Commons Oxy ID card payload. */
-const CARD_MATCHER = /^oxycommons:\/\/card(?:[/?#]|$)/i;
-/** URI scheme/host that introduces a real-life counterparty attestation payload. */
-const ATTEST_MATCHER = /^oxycommons:\/\/attest(?:[/?#]|$)/i;
-/**
- * Minimal, allocation-light query-string parser (no `URL` / `URLSearchParams`)
- * so it runs identically under Hermes and jsdom — mirrors the robustness of the
- * "Sign in with Oxy" approval-link parser. Shared by every `oxycommons://…`
- * payload parser in this module.
- */
-function parseCommonsQuery(raw) {
-    const params = new Map();
-    const qIndex = raw.indexOf('?');
-    if (qIndex < 0)
-        return params;
-    let query = raw.slice(qIndex + 1);
-    const hashIndex = query.indexOf('#');
-    if (hashIndex >= 0)
-        query = query.slice(0, hashIndex);
-    for (const pair of query.split('&')) {
-        if (pair.length === 0)
-            continue;
-        const eq = pair.indexOf('=');
-        const rawKey = eq < 0 ? pair : pair.slice(0, eq);
-        const rawValue = eq < 0 ? '' : pair.slice(eq + 1);
-        try {
-            params.set(decodeURIComponent(rawKey), decodeURIComponent(rawValue.replace(/\+/g, ' ')));
-        }
-        catch {
-            // Malformed percent-encoding — keep the raw token rather than throwing, so
-            // a single bad field doesn't sink an otherwise valid payload.
-            params.set(rawKey, rawValue);
-        }
-    }
-    return params;
-}
-/**
- * Parse a scanned / deep-linked Oxy ID payload (`oxycommons://card?did=…`) into
- * the referenced DID. Pure + dependency-free (Hermes-safe, no `URL` global) so
- * Commons (and any scanner) can reuse it without an OxyServices instance.
- *
- * @param raw - The raw scanned string or deep-link URL.
- * @returns `{ did }` when a usable DID is present; `null` for anything else (a
- *   non-card scheme, a missing/empty `did`, or non-string input).
- */
-export function parseIdPayload(raw) {
-    if (typeof raw !== 'string' || raw.trim().length === 0) {
-        return null;
-    }
-    const value = raw.trim();
-    if (!CARD_MATCHER.test(value)) {
-        return null;
-    }
-    const did = parseCommonsQuery(value).get('did');
-    if (!did || did.length === 0) {
-        return null;
-    }
-    return { did };
-}
-/**
- * Parse a scanned / deep-linked real-life-attestation payload
- * (`oxycommons://attest?subject=…&ctx=…&nonce=…&exp=…`). Pure + dependency-free
- * (Hermes-safe, no `URL` global), mirroring {@link parseIdPayload}, so Commons
- * (and any scanner) can reuse it without an OxyServices instance.
- *
- * @param raw - The raw scanned string or deep-link URL.
- * @returns `{ subjectDid, context, nonce, exp }` when the required fields are
- *   present and `exp` is a positive finite number; `null` otherwise (a non-attest
- *   scheme, a missing `subject`/`nonce`/`exp`, an unparseable `exp`, or non-string
- *   input). `context` defaults to `''` when the QR omits `ctx`.
- */
-export function parseAttestPayload(raw) {
-    if (typeof raw !== 'string' || raw.trim().length === 0) {
-        return null;
-    }
-    const value = raw.trim();
-    if (!ATTEST_MATCHER.test(value)) {
-        return null;
-    }
-    const params = parseCommonsQuery(value);
-    const subjectDid = params.get('subject');
-    const nonce = params.get('nonce');
-    const expRaw = params.get('exp');
-    if (!subjectDid || !nonce || expRaw === undefined || expRaw.length === 0) {
-        return null;
-    }
-    const exp = Number(expRaw);
-    if (!Number.isFinite(exp) || exp <= 0) {
-        return null;
-    }
-    return { subjectDid, context: params.get('ctx') ?? '', nonce, exp };
-}
-/**
- * Verify the Oxy custodial attestation on a public card.
- *
- * Re-canonicalizes the received `card` (so the order of the JSON keys on the
- * wire is irrelevant; `canonicalize` also omits any `undefined`-valued optional
- * key, matching the server which omits absent keys entirely) and checks the
- * `ES256K-DER-SHA256` signature against `attestation.publicKey`.
- *
- * NEVER throws: `verifySignature` already swallows malformed-input
- * errors and returns `false`, and an absent attestation short-circuits to
- * `false`. A pure, reusable helper (Commons can call it on a cached card).
- *
- * @param card - The card to verify (exactly as received).
- * @param attestation - The card's attestation, or `null` (unsigned ⇒ `false`).
- */
-export async function verifyPublicCardAttestation(card, attestation) {
-    if (!attestation) {
-        return false;
-    }
-    const { signature, publicKey } = attestation;
-    if (!signature || !publicKey) {
-        return false;
-    }
-    return verifySignature(canonicalize(card), signature, publicKey);
-}
-export function OxyServicesCivicMixin(Base) {
-    return class extends Base {
-        constructor(...args) {
-            super(...args);
-        }
-        /**
-         * Fetch a user's signed public Oxy ID card and verify the Oxy attestation
-         * client-side. Public (no auth required); short-TTL cached.
-         *
-         * Resolves to `{ card, attestation, verified }`. A bad/absent signature does
-         * NOT reject — it yields `verified: false` so the UI can warn. Only a
-         * transport failure (the fetch itself) rejects.
-         *
-         * @param userId - The subject account's Mongo `_id`. URL-encoded into the path.
-         */
-        async getPublicCard(userId) {
-            try {
-                const signed = await this.makeRequest('GET', `/civic/${encodeURIComponent(userId)}/card`, undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
-                const verified = await verifyPublicCardAttestation(signed.card, signed.attestation);
-                return { card: signed.card, attestation: signed.attestation, verified };
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Build the Oxy ID QR payload for the current user:
-         * `oxycommons://card?did=<did>&v=1`, where `<did>` is the user's Oxy DID
-         * (`did:web:oxy.so:u:<userId>`). The QR encodes ONLY the DID (anti-spoof — no
-         * trust data); a scanner resolves the signed card via {@link getPublicCard}.
-         * Round-trips through {@link parseIdPayload}.
-         *
-         * Throws if no user is authenticated (no DID to derive).
-         */
-        getMyIdPayload() {
-            const userId = this.getCurrentUserId();
-            if (!userId) {
-                throw new Error('No authenticated user — cannot build an Oxy ID payload.');
-            }
-            return `oxycommons://card?did=${buildUserDid(userId)}&v=1`;
-        }
-        // =========================================================================
-        // FASE 2 — real-life counterparty attestation (HIGH weight)
-        // =========================================================================
-        /**
-         * Build the real-life-attestation QR the current user (A) shows to be
-         * attested by a counterparty (B):
-         * `oxycommons://attest?subject=<A.did>&ctx=<context>&nonce=<fresh>&exp=<now+10m>`.
-         *
-         * A fresh crypto-random nonce is minted per call (single-use replay guard);
-         * `exp` is `now + 10min` (matching the server ceiling — scan promptly). The
-         * QR carries NO trust data; B re-signs and the server is authoritative. The
-         * returned `nonce`/`exp` let the displaying screen track which scan completed.
-         *
-         * Async because a crypto-secure nonce requires the platform RNG (async on
-         * native via expo-crypto). Throws if no user is authenticated.
-         *
-         * @param input.context - An opaque interaction id describing the encounter.
-         */
-        async buildAttestQrPayload(input) {
-            const userId = this.getCurrentUserId();
-            if (!userId) {
-                throw new Error('No authenticated user — cannot build an attestation QR.');
-            }
-            const subject = buildUserDid(userId);
-            const nonce = await SignatureService.generateChallenge();
-            const exp = Date.now() + ATTEST_QR_TTL_MS;
-            const payload = `oxycommons://attest?subject=${subject}` +
-                `&ctx=${encodeURIComponent(input.context)}` +
-                `&nonce=${nonce}&exp=${exp}`;
-            return { payload, nonce, exp };
-        }
-        /**
-         * Submit a real-life counterparty attestation as the SCANNER (B): sign a
-         * self-issued `real_life_attestation` v2 record on B's own chain
-         * (`subject === issuer === B.did`), referencing A via `record.about`, then
-         * `POST /civic/attestations`. The server enforces nonce single-use,
-         * freshness, graph-exclusion (B is not A's puppet), and the per-pair
-         * cooldown, then awards A the HIGH-weight points.
-         *
-         * NATIVE-ONLY (signs with the on-device key; throws on web / when no
-         * identity or no authenticated user). The record is keyed
-         * `collection: 'app.oxy.attestation'`, `rkey: <nonce>`.
-         *
-         * @param input - The parsed QR fields ({@link ParsedAttestPayload}) plus B's
-         *   optional `geohash` / `biometricOk` support signals.
-         */
-        async submitRealLifeAttestation(input) {
-            try {
-                const envelope = await this._signMyCivicRecordV2('real_life_attestation', {
-                    about: input.subjectDid,
-                    context: input.context,
-                    nonce: input.nonce,
-                    exp: input.exp,
-                    ...(input.geohash !== undefined ? { geohash: input.geohash } : {}),
-                    ...(input.biometricOk !== undefined ? { biometricOk: input.biometricOk } : {}),
-                }, ATTEST_COLLECTION, input.nonce);
-                return await this.makeRequest('POST', '/civic/attestations', envelope, { cache: false });
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        // =========================================================================
-        // FASE 2 — validator / jury (MEDIUM weight)
-        // =========================================================================
-        /**
-         * List the current user's pending jury duties (`GET /civic/validations/inbox`).
-         * Auth required; never cached (the inbox is a live queue). Returns `[]` when
-         * the caller is on no juries.
-         */
-        async getValidatorInbox() {
-            try {
-                const res = await this.makeRequest('GET', '/civic/validations/inbox', undefined, { cache: false });
-                return res.requests ?? [];
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Cast a SIGNED verdict on a validation request as a selected juror: sign a
-         * self-issued `validation_verdict` v2 record on the juror's own chain bound
-         * to `requestId` + `payloadHash` (so a verdict cannot be replayed onto a
-         * different request or an altered payload), then
-         * `POST /civic/validations/:id/vote`.
-         *
-         * NATIVE-ONLY (signs with the on-device key; throws on web / when no
-         * identity or no authenticated user). The record is keyed
-         * `collection: 'app.oxy.validation'`, `rkey: <requestId>`.
-         *
-         * @param requestId - The validation request being voted on.
-         * @param payloadHash - The request's canonical payload hash (from the inbox);
-         *   the server rejects a vote whose hash does not match the stored request.
-         * @param verdict - `'valid'` | `'invalid'` | `'abstain'`.
-         */
-        async submitValidationVote(requestId, payloadHash, verdict) {
-            try {
-                const envelope = await this._signMyCivicRecordV2('validation_verdict', { requestId, payloadHash, verdict }, VALIDATION_COLLECTION, requestId);
-                return await this.makeRequest('POST', `/civic/validations/${encodeURIComponent(requestId)}/vote`, envelope, { cache: false });
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Recuse from a validation request (`POST /civic/validations/:id/deny`): the
-         * juror is removed from the jury and the request is re-tallied. Auth
-         * required; no signed record (recusal is not an attestation).
-         *
-         * @param requestId - The validation request to recuse from.
-         */
-        async denyValidation(requestId) {
-            try {
-                return await this.makeRequest('POST', `/civic/validations/${encodeURIComponent(requestId)}/deny`, undefined, { cache: false });
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        // =========================================================================
-        // FASE 3 — proof-of-personhood web-of-trust (staked vouch)
-        // =========================================================================
-        /**
-         * Vouch that another user is a real person as the VOUCHER (B): sign a
-         * self-issued `personhood_vouch` v2 record on B's own chain
-         * (`subject === issuer === B.did`), referencing the subject (A) via
-         * `record.about`, then `POST /civic/personhood/vouch`. The server verifies
-         * it, enforces the voucher-eligibility (personhood ≥ τ) + graph-exclusion
-         * gates, stakes B, awards A `personhood_vouched`, and recomputes A's
-         * personhood. The voucher id is resolved server-side from the session — never
-         * from the body.
-         *
-         * The signed record matches the API schema: `{ about, stake?, … }` — note the
-         * wire field is `stake` (the caller's `stakeAmount` request), distinct from
-         * the server-clamped `VouchResult.stakeAmount` it returns. The optional
-         * `biometricOk` is carried as a signed support signal.
-         *
-         * NATIVE-ONLY (signs with the on-device key; throws on web / when no identity
-         * or no authenticated user). The record is keyed
-         * `collection: 'app.oxy.vouch'`, `rkey: <subjectDid>` (one vouch per subject
-         * on the voucher's chain — last-writer-wins). After a successful vouch the
-         * personhood + `/users/me` GET caches are swept.
-         *
-         * @param input - The subject DID plus B's optional stake / biometric signal.
-         */
-        async vouchForPerson(input) {
-            try {
-                const envelope = await this._signMyCivicRecordV2('personhood_vouch', {
-                    about: input.subjectDid,
-                    ...(input.stakeAmount !== undefined ? { stake: input.stakeAmount } : {}),
-                    ...(input.biometricOk !== undefined ? { biometricOk: input.biometricOk } : {}),
-                }, VOUCH_COLLECTION, input.subjectDid);
-                const result = await this.makeRequest('POST', '/civic/personhood/vouch', envelope, { cache: false });
-                this._sweepPersonhoodCaches();
-                return result;
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Withdraw the current user's active vouch for a subject
-         * (`DELETE /civic/personhood/vouch/:subjectUserId`). The vouch flips to
-         * `withdrawn` server-side and the subject is recomputed (which may demote
-         * them below θ). Auth required; no signed record (withdrawal is not an
-         * attestation). After a successful withdraw the personhood + `/users/me` GET
-         * caches are swept.
-         *
-         * @param subjectUserId - The subject account's Mongo `_id` (NOT a DID) — the
-         *   id the server keys the vouch on. URL-encoded into the path.
-         */
-        async withdrawVouch(subjectUserId) {
-            try {
-                const result = await this.makeRequest('DELETE', `/civic/personhood/vouch/${encodeURIComponent(subjectUserId)}`, undefined, { cache: false });
-                this._sweepPersonhoodCaches();
-                return result;
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Fetch a user's public personhood status snapshot
-         * (`GET /civic/personhood/:userId`). Read-only: the server returns the cached
-         * snapshot, or a zeroed `unverified` shape (`breakdown`/`updatedAt` null) when
-         * none exists yet. Public (no auth required); short-TTL cached.
-         *
-         * @param userId - The subject account's Mongo `_id`. URL-encoded into the path.
-         */
-        async getPersonhood(userId) {
-            try {
-                return await this.makeRequest('GET', `/civic/personhood/${encodeURIComponent(userId)}`, undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Fetch the CURRENT user's personhood status ({@link getPersonhood} for the
-         * authenticated user's id). Throws if no user is authenticated.
-         */
-        async getMyPersonhood() {
-            const userId = this.getCurrentUserId();
-            if (!userId) {
-                throw new Error('No authenticated user — cannot resolve personhood status.');
-            }
-            return this.getPersonhood(userId);
-        }
-        // =========================================================================
-        // FASE 4 — verifiable credentials
-        // =========================================================================
-        /**
-         * Issue a verifiable credential as the ISSUER: sign a self-issued
-         * `credential` v2 record on the caller's own chain
-         * (`subject === issuer === issuer.did`) whose `record.about` is the HOLDER's
-         * DID (the W3C `credentialSubject`), then `POST /civic/credentials`. The
-         * server verifies the signature + the issuer's CURRENT verification method +
-         * chain continuity, stores the signed record, and projects a queryable
-         * credential row. All claim data comes from the SIGNED envelope — the issuer
-         * id is resolved server-side from the session, never from the body.
-         *
-         * `'VerifiableCredential'` is ensured present as the base type (prepended
-         * when the caller omits it; the server rejects a record missing it). An
-         * `expiresAt` ISO string is converted to the epoch-ms the signed record
-         * carries (the server rejects a past expiry).
-         *
-         * NATIVE-ONLY (signs with the on-device key; throws on web / when no identity
-         * or no authenticated user). The record is keyed
-         * `collection: 'app.oxy.credential'`, `rkey: <fresh unique nonce>` (each
-         * credential is a distinct chain entry, so the rkey must be unique per
-         * credential). After a successful issue the credential GET caches are swept.
-         *
-         * @param input - The holder DID, VC types, claims, and optional ISO expiry.
-         */
-        async issueCredential(input) {
-            try {
-                const types = input.types.includes(CREDENTIAL_BASE_TYPE)
-                    ? input.types
-                    : [CREDENTIAL_BASE_TYPE, ...input.types];
-                let expiresAtMs;
-                if (input.expiresAt !== undefined) {
-                    const parsed = Date.parse(input.expiresAt);
-                    if (Number.isNaN(parsed)) {
-                        throw new Error('Invalid expiresAt — must be an ISO 8601 date string.');
-                    }
-                    expiresAtMs = parsed;
-                }
-                const record = {
-                    about: input.holderDid,
-                    types,
-                    claims: input.claims,
-                    ...(expiresAtMs !== undefined ? { expiresAt: expiresAtMs } : {}),
-                };
-                // A fresh crypto-random rkey: every credential is its own chain entry, so
-                // (unlike the one-per-subject vouch keyed on the subject DID) the rkey
-                // must be unique per credential or a second credential would collide.
-                const rkey = await SignatureService.generateChallenge();
-                const envelope = await this._signMyCivicRecordV2('credential', record, CREDENTIAL_COLLECTION, rkey);
-                const result = await this.makeRequest('POST', '/civic/credentials', envelope, { cache: false });
-                this._sweepCredentialCaches();
-                return result;
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * List a holder's verifiable credentials
-         * (`GET /civic/credentials/:holderUserId`), newest first, optionally filtered
-         * by stored `status`. Public (credentials are issuer-signed attestations a
-         * holder collects to SHOW); short-TTL cached and swept after the caller's own
-         * issue / revoke. An unknown holder yields an empty list.
-         *
-         * @param holderUserId - The holder account's Mongo `_id` (NOT a DID). URL-encoded.
-         * @param opts.status - Optional `'active' | 'revoked' | 'expired'` filter.
-         */
-        async listCredentials(holderUserId, opts = {}) {
-            try {
-                const base = `/civic/credentials/${encodeURIComponent(holderUserId)}`;
-                const url = opts.status ? `${base}?status=${encodeURIComponent(opts.status)}` : base;
-                return await this.makeRequest('GET', url, undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * List the CURRENT user's verifiable credentials ({@link listCredentials} for
-         * the authenticated user's id). Throws if no user is authenticated.
-         *
-         * @param opts.status - Optional status filter.
-         */
-        async listMyCredentials(opts = {}) {
-            const userId = this.getCurrentUserId();
-            if (!userId) {
-                throw new Error('No authenticated user — cannot list credentials.');
-            }
-            return this.listCredentials(userId, opts);
-        }
-        /**
-         * Verify a credential by its signed-record id
-         * (`GET /civic/credentials/by-record/:recordId/verify`). The server recomputes
-         * the canonical signing input from the STORED envelope and verifies the
-         * signature against a CURRENT verification method of the ISSUER DID (so a
-         * key the issuer has since rotated away no longer verifies), then checks the
-         * credential is neither revoked nor expired. Public; short-TTL cached
-         * (matching the server's `max-age=60`) and swept after the caller's own issue
-         * / revoke.
-         *
-         * A revoked / expired / unverifiable credential yields `valid: false` (NOT a
-         * throw) so the UI can render it as untrusted; `credential` is `null` only
-         * when no credential exists for the record id. Only a transport failure (the
-         * fetch itself) rejects.
-         *
-         * @param recordId - The credential's signed-record id. URL-encoded into the path.
-         */
-        async verifyCredential(recordId) {
-            try {
-                return await this.makeRequest('GET', `/civic/credentials/by-record/${encodeURIComponent(recordId)}/verify`, undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Revoke a credential the current user originally issued
-         * (`POST /civic/credentials/:id/revoke`). Only the original USER issuer may
-         * revoke; the server flips the credential to `revoked`. After a successful
-         * revoke the credential GET caches are swept.
-         *
-         * @param id - The credential's id (the projection row `_id`, NOT the signed
-         *   record id). URL-encoded into the path.
-         */
-        async revokeCredential(id) {
-            try {
-                const result = await this.makeRequest('POST', `/civic/credentials/${encodeURIComponent(id)}/revoke`, undefined, { cache: false });
-                this._sweepCredentialCaches();
-                return result;
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Sweep the credential GET caches an issue / revoke invalidates: every
-         * credential read (the holder list + the by-record verify, which share the
-         * `GET:/civic/credentials/` prefix) so a re-read reflects the new credential
-         * set / status. Public rather than `private` for the same TS4094 reason as
-         * {@link _signMyCivicRecordV2}.
-         */
-        _sweepCredentialCaches() {
-            this.clearCacheByPrefix(CREDENTIAL_CACHE_PREFIX);
-        }
-        /**
-         * Sweep the GET caches a vouch / withdraw can invalidate: every personhood
-         * status read (the subject's snapshot changed) and `/users/me` (a subject
-         * crossing the threshold flips their mirrored `User.verified`). Public rather
-         * than `private` for the same TS4094 reason as {@link _signMyCivicRecordV2}.
-         */
-        _sweepPersonhoodCaches() {
-            this.clearCacheByPrefix(PERSONHOOD_CACHE_PREFIX);
-            this.clearCacheByPrefix(USERS_ME_CACHE_PREFIX);
-        }
-        /**
-         * Sign a self-issued v2 signed-record envelope on the CURRENT user's own
-         * per-subject hash chain. Fetches the caller's chain head fresh (uncached, so
-         * `seq`/`prev` are never stale → no `bad_seq`/`chain_fork`) and signs with
-         * {@link SignatureService.signRecordV2}.
-         *
-         * NATIVE-ONLY (the private key lives in native secure storage). Internal
-         * helper (leading underscore); public rather than `private` because mixins
-         * compose into an exported anonymous class where TypeScript cannot represent a
-         * private member in the emitted declaration file (TS4094).
-         *
-         * @param type - The signed-record category.
-         * @param record - The record payload (canonicalized into the signed bytes).
-         * @param collection - The AtProto-style collection namespace.
-         * @param rkey - The AtProto-style record key within the collection.
-         */
-        async _signMyCivicRecordV2(type, record, collection, rkey) {
-            const userId = this.getCurrentUserId();
-            if (!userId) {
-                throw new Error('No authenticated user — cannot sign a civic record.');
-            }
-            const subject = buildUserDid(userId);
-            const head = await this.makeRequest('GET', `/identity/records/${encodeURIComponent(userId)}/chain/head`, undefined, { cache: false });
-            return SignatureService.signRecordV2(type, subject, record, {
-                seq: head.seq + 1,
-                prev: head.headRecordId,
-                collection,
-                rkey,
-            });
-        }
-    };
-}