@oxy.so/contracts 4.16.0 → 4.17.0

package/dist/esm/client/check.js

@@ -0,0 +1,428 @@
+/**
+ * Structural checks for contract values, without Zod.
+ *
+ * The Zod schemas in this package are the contract, and the API parses with
+ * them. A client only needs to know that a response has the shape its type
+ * promises, and Zod's object schemas pull Zod's whole runtime into every app
+ * that bundles the SDK (~120 KB before compression, evaluated at startup). The
+ * checks here give the client the same answers in plain TypeScript.
+ *
+ * Every check mirrors one Zod 3 schema in this package, and
+ * `__tests__/clientChecks.parity.test.ts` runs both over the same inputs and
+ * requires the same verdict, the same output and the same failing path. The
+ * rules follow Zod 3 exactly:
+ *
+ *   string(...rules)      a string; `trim`/`toLowerCase` rewrite it, the other
+ *                         rules test it, in the order given
+ *   number(...rules)      a number that is not NaN (Infinity passes, as in Zod)
+ *   literal(v) / oneOf    `===` one value / one of a fixed set of strings
+ *   optional(c)           `undefined` (or an absent key) passes; `null` does not
+ *   nullable(c)           `null` passes and is kept
+ *   withDefault(c, v)     `undefined` becomes `v`, which is then checked
+ *   array(c, ...rules)    the size rules first, then every element in order
+ *   object(shape)         unknown keys are DROPPED (Zod's default "strip")
+ *   strictObject(shape)   unknown keys FAIL (`.strict()`)
+ *   looseObject(shape)    unknown keys are KEPT (`.passthrough()`)
+ *   refine(c, test)       a further condition, run once `c` passes
+ *   union / discriminatedUnion   as Zod 3 reports them
+ *
+ * A failure carries the first issue Zod would report and whether Zod would have
+ * stopped there (`fatal`: the type was wrong) or kept checking (`fatal: false`:
+ * only a rule failed). Only `union` reads the difference, because Zod reports a
+ * union through its first "rule failed" option.
+ *
+ * This module, and everything under `src/client/`, must never import `zod`
+ * (`__tests__/clientEntryGraph.test.ts` walks the graph).
+ */
+function ok(value) {
+    return { ok: true, value };
+}
+function fail(path, problem, fatal) {
+    return { ok: false, issue: { path, ...problem }, fatal };
+}
+function describe(input) {
+    if (input === null)
+        return 'null';
+    if (Array.isArray(input))
+        return 'array';
+    if (typeof input === 'number' && Number.isNaN(input))
+        return 'nan';
+    return typeof input;
+}
+/** Zod's wording for a value of the wrong type. */
+function wrongType(path, expected, input) {
+    const received = describe(input);
+    const message = input === undefined ? 'Required' : `Expected ${expected}, received ${received}`;
+    return fail(path, { code: 'invalid_type', message, expected, received }, true);
+}
+/** `'a' | 'b'` — how Zod lists allowed values. */
+function listValues(values, separator = ' | ') {
+    return values
+        .map((value) => (typeof value === 'string' ? `'${value}'` : String(value)))
+        .join(separator);
+}
+function isRecord(input) {
+    return typeof input === 'object' && input !== null && !Array.isArray(input);
+}
+export const trim = { rewrite: (value) => value.trim() };
+export const toLowerCase = { rewrite: (value) => value.toLowerCase() };
+export function minLength(min, message) {
+    return {
+        test: (value) => value.length >= min,
+        code: 'too_small',
+        message: message ?? `String must contain at least ${min} character(s)`,
+    };
+}
+export function maxLength(max, message) {
+    return {
+        test: (value) => value.length <= max,
+        code: 'too_big',
+        message: message ?? `String must contain at most ${max} character(s)`,
+    };
+}
+export function pattern(regex, message) {
+    return {
+        test: (value) => {
+            regex.lastIndex = 0;
+            return regex.test(value);
+        },
+        code: 'invalid_string',
+        message: message ?? 'Invalid',
+    };
+}
+export function startsWith(prefix) {
+    return {
+        test: (value) => value.startsWith(prefix),
+        code: 'invalid_string',
+        message: `Invalid input: must start with "${prefix}"`,
+    };
+}
+/** Zod 3's `.email()`. */
+const EMAIL = /^(?!\.)(?!.*\.\.)([A-Z0-9_'+\-.]*)[A-Z0-9_+-]@([A-Z0-9][A-Z0-9-]*\.)+[A-Z]{2,}$/i;
+export const email = pattern(EMAIL, 'Invalid email');
+/** Zod 3's `.url()`: anything `new URL()` accepts. */
+export const url = {
+    test: (value) => {
+        try {
+            new URL(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    code: 'invalid_string',
+    message: 'Invalid url',
+};
+/** Zod 3's `.datetime()`: ISO 8601 in UTC (`Z`), any sub-second precision, leap days checked. */
+const DATETIME = new RegExp('^((\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-((0[13578]|1[02])-(0[1-9]|[12]\\d|3[01])|(0[469]|11)-(0[1-9]|[12]\\d|30)|(02)-(0[1-9]|1\\d|2[0-8])))' +
+    'T([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d(\\.\\d+)?)?(Z)$');
+export const datetime = pattern(DATETIME, 'Invalid datetime');
+export function string(...rules) {
+    return (input, path) => {
+        if (typeof input !== 'string')
+            return wrongType(path, 'string', input);
+        let value = input;
+        let firstFailure = null;
+        for (const rule of rules) {
+            if ('rewrite' in rule)
+                value = rule.rewrite(value);
+            else if (firstFailure === null && !rule.test(value)) {
+                firstFailure = { code: rule.code, message: rule.message };
+            }
+        }
+        return firstFailure === null ? ok(value) : fail(path, firstFailure, false);
+    };
+}
+/** Zod's `.int()` — reported, as Zod does, as an `invalid_type` that does not stop the parse. */
+export const int = (value) => Number.isInteger(value)
+    ? undefined
+    : {
+        code: 'invalid_type',
+        message: 'Expected integer, received float',
+        expected: 'integer',
+        received: 'float',
+    };
+export function atLeast(min) {
+    return (value) => value >= min
+        ? undefined
+        : { code: 'too_small', message: `Number must be greater than or equal to ${min}` };
+}
+export function atMost(max) {
+    return (value) => value <= max
+        ? undefined
+        : { code: 'too_big', message: `Number must be less than or equal to ${max}` };
+}
+/** Zod's `.positive()`. */
+export const positive = (value) => value > 0 ? undefined : { code: 'too_small', message: 'Number must be greater than 0' };
+/** Zod's `.nonnegative()` (and `.min(0)`). */
+export const nonnegative = atLeast(0);
+/** Zod's `.safe()`: both bounds, low first. */
+export const safe = (value) => atLeast(Number.MIN_SAFE_INTEGER)(value) ?? atMost(Number.MAX_SAFE_INTEGER)(value);
+export function number(...rules) {
+    return (input, path) => {
+        if (typeof input !== 'number' || Number.isNaN(input))
+            return wrongType(path, 'number', input);
+        for (const rule of rules) {
+            const problem = rule(input);
+            if (problem)
+                return fail(path, problem, false);
+        }
+        return ok(input);
+    };
+}
+export const boolean = (input, path) => typeof input === 'boolean' ? ok(input) : wrongType(path, 'boolean', input);
+export function literal(expected) {
+    return (input, path) => input === expected
+        ? ok(expected)
+        : fail(path, {
+            code: 'invalid_literal',
+            message: `Invalid literal value, expected ${JSON.stringify(expected)}`,
+        }, true);
+}
+/** One of a fixed set of strings — Zod's `z.enum`. */
+export function oneOf(values) {
+    return (input, path) => {
+        if (typeof input !== 'string')
+            return wrongType(path, listValues(values), input);
+        return values.includes(input)
+            ? ok(input)
+            : fail(path, {
+                code: 'invalid_enum_value',
+                message: `Invalid enum value. Expected ${listValues(values)}, received '${input}'`,
+            }, true);
+    };
+}
+/* -------------------------------------------------------------------------- */
+/*  Wrappers                                                                  */
+/* -------------------------------------------------------------------------- */
+export function optional(inner) {
+    return (input, path) => (input === undefined ? ok(undefined) : inner(input, path));
+}
+export function nullable(inner) {
+    return (input, path) => (input === null ? ok(null) : inner(input, path));
+}
+export function withDefault(inner, fallback) {
+    return (input, path) => inner(input === undefined ? fallback : input, path);
+}
+/** A further condition on a value `inner` accepted. */
+export function refine(inner, test, message) {
+    return (input, path) => {
+        const checked = inner(input, path);
+        if (!checked.ok)
+            return checked;
+        return test(checked.value) ? checked : fail(path, { code: 'custom', message }, false);
+    };
+}
+/**
+ * Zod's `.superRefine()` for the one-issue case: `test` returns the first
+ * problem (its path relative to the value) or `undefined`.
+ */
+export function refineAt(inner, test) {
+    return (input, path) => {
+        const checked = inner(input, path);
+        if (!checked.ok)
+            return checked;
+        const problem = test(checked.value);
+        return problem
+            ? fail([...path, ...problem.path], { code: 'custom', message: problem.message }, false)
+            : checked;
+    };
+}
+/** Narrows a checked value to a branded contract type (Zod's `.brand()`). */
+export function branded(inner) {
+    return inner;
+}
+/**
+ * The issues of a container, as Zod 3 orders them: the first one is reported,
+ * and the container is fatal when any part of it was.
+ */
+class Failures {
+    constructor(first) {
+        this.fatal = false;
+        this.first = first;
+    }
+    add(failure) {
+        this.first ?? (this.first = failure.issue);
+        this.fatal || (this.fatal = failure.fatal);
+    }
+    result() {
+        return this.first ? { ok: false, issue: this.first, fatal: this.fatal } : null;
+    }
+}
+export function minItems(min) {
+    return {
+        test: (length) => length >= min,
+        code: 'too_small',
+        message: `Array must contain at least ${min} element(s)`,
+    };
+}
+export function maxItems(max) {
+    return {
+        test: (length) => length <= max,
+        code: 'too_big',
+        message: `Array must contain at most ${max} element(s)`,
+    };
+}
+/** Zod's `.length(n)`: `too_big` or `too_small`, by which side it missed. */
+export function exactItems(count) {
+    const message = `Array must contain exactly ${count} element(s)`;
+    return [
+        { test: (length) => length <= count, code: 'too_big', message },
+        { test: (length) => length >= count, code: 'too_small', message },
+    ];
+}
+export function array(inner, ...rules) {
+    const sizeRules = rules.flat();
+    return (input, path) => {
+        if (!Array.isArray(input))
+            return wrongType(path, 'array', input);
+        // Zod reports the size before any element, then every element in order.
+        const size = sizeRules.find((rule) => !rule.test(input.length));
+        const failures = new Failures(size ? { path, code: size.code, message: size.message } : null);
+        const out = [];
+        for (let index = 0; index < input.length; index++) {
+            const checked = inner(input[index], [...path, index]);
+            if (checked.ok)
+                out.push(checked.value);
+            else
+                failures.add(checked);
+        }
+        return failures.result() ?? ok(out);
+    };
+}
+function objectWith(shape, unknownKeys) {
+    const keys = Object.keys(shape);
+    return (input, path) => {
+        if (!isRecord(input))
+            return wrongType(path, 'object', input);
+        const failures = new Failures(null);
+        const out = {};
+        for (const key of keys) {
+            const checked = shape[key](input[key], [...path, key]);
+            if (!checked.ok)
+                failures.add(checked);
+            // An optional key the input did not send stays absent rather than
+            // appearing as `key: undefined` — what Zod does, and what `in` sees.
+            else if (key !== '__proto__' && (checked.value !== undefined || key in input)) {
+                out[key] = checked.value;
+            }
+        }
+        if (unknownKeys !== 'strip') {
+            const unknown = [];
+            for (const key in input) {
+                if (keys.includes(key))
+                    continue;
+                unknown.push(key);
+                if (unknownKeys === 'passthrough' && key !== '__proto__' && input[key] !== undefined) {
+                    out[key] = input[key];
+                }
+            }
+            if (unknownKeys === 'strict' && unknown.length > 0) {
+                const message = `Unrecognized key(s) in object: ${listValues(unknown, ', ')}`;
+                failures.add({ issue: { path, code: 'unrecognized_keys', message }, fatal: false });
+            }
+        }
+        return failures.result() ?? ok(out);
+    };
+}
+/** Unknown keys are dropped — Zod's `z.object(shape)`. */
+export function object(shape) {
+    return objectWith(shape, 'strip');
+}
+/** Unknown keys fail — Zod's `z.object(shape).strict()`. */
+export function strictObject(shape) {
+    return objectWith(shape, 'strict');
+}
+/** Unknown keys are kept as sent — Zod's `z.object(shape).passthrough()`. */
+export function looseObject(shape) {
+    return objectWith(shape, 'passthrough');
+}
+/** Any object, every value kept — Zod's `z.record(z.unknown())`. */
+export const unknownRecord = (input, path) => {
+    if (!isRecord(input))
+        return wrongType(path, 'object', input);
+    const out = {};
+    for (const key in input)
+        if (key !== '__proto__')
+            out[key] = input[key];
+    return ok(out);
+};
+/* -------------------------------------------------------------------------- */
+/*  Unions                                                                    */
+/* -------------------------------------------------------------------------- */
+/** The first option that passes; else Zod 3's report (the first option that only failed a rule). */
+export function union(...options) {
+    return (input, path) => {
+        let ruleFailure = null;
+        for (const option of options) {
+            const checked = option(input, path);
+            if (checked.ok)
+                return checked;
+            if (!checked.fatal)
+                ruleFailure ?? (ruleFailure = checked);
+        }
+        return ruleFailure ?? fail(path, { code: 'invalid_union', message: 'Invalid input' }, true);
+    };
+}
+/** Zod 3's `z.discriminatedUnion(key, options)`, with the options keyed by their tag. */
+export function discriminatedUnion(key, options) {
+    return (input, path) => {
+        if (!isRecord(input))
+            return wrongType(path, 'object', input);
+        const tag = input[key];
+        const option = typeof tag === 'string' && Object.prototype.hasOwnProperty.call(options, tag)
+            ? options[tag]
+            : undefined;
+        if (!option) {
+            const message = `Invalid discriminator value. Expected ${listValues(Object.keys(options))}`;
+            return fail([...path, key], { code: 'invalid_union_discriminator', message }, true);
+        }
+        return option(input, path);
+    };
+}
+/* -------------------------------------------------------------------------- */
+/*  Using a check                                                             */
+/* -------------------------------------------------------------------------- */
+/** `a.b[0].c` — for messages. */
+export function formatCheckPath(path) {
+    let out = '';
+    for (const part of path) {
+        out += typeof part === 'number' ? `[${part}]` : out ? `.${part}` : part;
+    }
+    return out || '(root)';
+}
+/**
+ * A value did not have the shape its contract requires. Thrown where a Zod
+ * schema's `.parse()` used to throw a `ZodError`; `issues` keeps that error's
+ * issue shape (`code`, `path`, `message`), holding the first issue Zod reports.
+ */
+export class ContractCheckError extends Error {
+    constructor(issue, context) {
+        const where = formatCheckPath(issue.path);
+        super(`${context ? `${context}: ` : ''}${where}: ${issue.message}`);
+        this.name = 'ContractCheckError';
+        this.issues = [issue];
+        Object.setPrototypeOf(this, ContractCheckError.prototype);
+    }
+}
+/** The checked value, or `null` — the twin of `safeParseContract`. */
+export function checkContract(check, input) {
+    const checked = check(input, []);
+    return checked.ok ? checked.value : null;
+}
+/** The checked value; throws {@link ContractCheckError} — the twin of a schema's `.parse()`. */
+export function parseContract(check, input, context) {
+    const checked = check(input, []);
+    if (!checked.ok)
+        throw new ContractCheckError(checked.issue, context);
+    return checked.value;
+}
+/**
+ * `exact<DeviceSessionState>()(check)` compiles only when `check` produces
+ * exactly `DeviceSessionState` — every key, every optional mark, every literal
+ * — so a contract type that changes without its check is a type error here.
+ */
+export function exact() {
+    return (check) => check;
+}

package/dist/esm/client/deviceBoot.js

@@ -0,0 +1,19 @@
+/**
+ * The first-party login result check, without Zod. Schemas: `../deviceBoot.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+import { array, exact, object, optional, string } from './check.js';
+const securityAlert = object({
+    message: string(),
+    anomalies: array(object({ type: string(), reason: string(), details: optional(string()) })),
+});
+export const loginResultCheck = exact()(object({
+    sessionId: string(),
+    deviceId: string(),
+    expiresAt: string(),
+    accessToken: optional(string()),
+    deviceSecret: optional(string()),
+    securityAlert: optional(securityAlert),
+    user: object({ id: string(), username: optional(string()), avatar: optional(string()) }),
+}));

package/dist/esm/client/deviceDirectory.js

@@ -0,0 +1,48 @@
+/**
+ * Device-directory checks, without Zod. Schemas: `../deviceDirectory.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+import { ACCOUNT_KINDS } from './accountGraph.js';
+import { array, boolean, exact, int, minLength, nonnegative, nullable, number, object, oneOf, optional, string, } from './check.js';
+import { activeTokenCheck, deviceSessionStateCheck } from './deviceSession.js';
+import { userNameCheck } from './userResponse.js';
+const DEVICE_CONTEXT_RELATIONSHIPS = ['self', 'owner', 'member'];
+const profile = object({
+    id: string(minLength(1)),
+    username: string(),
+    name: optional(userNameCheck),
+    avatar: optional(nullable(string())),
+    color: optional(nullable(string())),
+});
+const accountContext = object({
+    id: string(minLength(1)),
+    accountId: string(minLength(1)),
+    kind: oneOf(ACCOUNT_KINDS),
+    relationship: oneOf(DEVICE_CONTEXT_RELATIONSHIPS),
+    account: profile,
+    onDevice: boolean,
+    available: boolean,
+    active: boolean,
+    lastUsedAt: nullable(number()),
+});
+const principal = object({
+    id: string(minLength(1)),
+    userId: string(minLength(1)),
+    authuser: number(int, nonnegative),
+    user: profile,
+    contexts: array(accountContext),
+});
+export const deviceDirectoryCheck = exact()(object({
+    deviceId: string(minLength(1)),
+    revision: number(int, nonnegative),
+    activeContextId: nullable(string()),
+    principals: array(principal),
+    updatedAt: number(),
+}));
+export const deviceActivateResponseCheck = exact()(object({ directory: deviceDirectoryCheck, activeToken: nullable(activeTokenCheck) }));
+export const deviceDirectorySyncCheck = exact()(object({
+    directory: deviceDirectoryCheck,
+    state: deviceSessionStateCheck,
+    activeToken: nullable(activeTokenCheck),
+}));

package/dist/esm/client/deviceSession.js

@@ -0,0 +1,60 @@
+/**
+ * Device-session checks, without Zod. Schemas: `../deviceSession.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+import { array, exact, int, minLength, nonnegative, nullable, number, object, oneOf, optional, positive, string, } from './check.js';
+/* -------------------------------------------------------------------------- */
+/*  Instant cross-app session sync (token-free socket signal)                 */
+/* -------------------------------------------------------------------------- */
+/**
+ * Name of the token-free Socket.IO event emitted to room `user:<userId>` on
+ * every DeviceSession mutation that changes what is signed in for that user.
+ *
+ * This is a pure SIGNAL — it carries NO access token, NO deviceSecret and NO
+ * account bodies. A client that receives it re-fetches its authenticated
+ * session/account state (`GET /session/device/state`, `GET /accounts`). Unlike
+ * `session_state` (scoped to `device:<deviceId>`, i.e. a single origin), this
+ * reaches ALL of a user's connected sockets across their devices/origins so
+ * every Oxy app reflects an add / switch / signout instantly.
+ */
+export const SESSION_ACCOUNTS_CHANGED_EVENT = 'session_accounts_changed';
+/* -------------------------------------------------------------------------- */
+/*  Response checks                                                           */
+/* -------------------------------------------------------------------------- */
+const SESSION_ACCOUNTS_CHANGED_REASONS = ['login', 'add', 'switch', 'signout', 'revoke'];
+const sessionAccount = object({
+    accountId: string(),
+    sessionId: string(),
+    authuser: number(int, nonnegative),
+    operatedByUserId: optional(string()),
+});
+export const deviceSessionStateCheck = exact()(object({
+    deviceId: string(),
+    accounts: array(sessionAccount),
+    activeAccountId: nullable(string()),
+    revision: number(int, nonnegative),
+    updatedAt: number(),
+}));
+export const activeTokenCheck = exact()(object({ accessToken: string(), expiresAt: string() }));
+export const deviceSessionSyncCheck = exact()(object({ state: deviceSessionStateCheck, activeToken: nullable(activeTokenCheck) }));
+export const deviceTokenMintResponseCheck = exact()(object({
+    accessToken: string(),
+    expiresAt: string(),
+    nextDeviceSecret: string(),
+    state: deviceSessionStateCheck,
+}));
+export const sessionAccountsChangedEventCheck = exact()(object({
+    userId: string(),
+    revision: number(int, nonnegative),
+    reason: oneOf(SESSION_ACCOUNTS_CHANGED_REASONS),
+}));
+export const deviceBackgroundCredentialResponseCheck = exact()(object({
+    deviceId: string(minLength(1)),
+    secret: string(minLength(1)),
+    accountId: string(minLength(1)),
+    expiresAt: string(),
+}));
+export const deviceRegisterResponseCheck = exact()(object({ deviceId: string(minLength(1)), deviceSecret: string(minLength(1)) }));
+export const deviceJoinResponseCheck = exact()(deviceRegisterResponseCheck);
+export const deviceJoinCodeResponseCheck = exact()(object({ code: string(minLength(1)), expiresIn: number(int, positive) }));

package/dist/esm/client/externalIdentity.js

@@ -0,0 +1,16 @@
+/**
+ * The external-identity reference check, without Zod. Schemas: `../externalIdentity.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+import { exact, minLength, object, oneOf, string } from './check.js';
+const required = string(minLength(1));
+/** One Oxy-proven network alias of a profile — the twin of `externalIdentityReferenceSchema`. */
+export const externalIdentityReferenceCheck = exact()(object({
+    canonicalAcct: required,
+    network: required,
+    protocol: oneOf(['activitypub', 'atproto', 'instagram-graph']),
+    actorUri: required,
+    transportAcct: required,
+    sourceUserId: required,
+}));

package/dist/esm/client/identity.js

@@ -0,0 +1,42 @@
+/**
+ * The signed-record envelope check, without Zod. Schemas: `../identity.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+import { exact, int, literal, minLength, nonnegative, nullable, number, object, optional, refineAt, string, union, unknownRecord, } from './check.js';
+const CHAIN_FIELDS = ['seq', 'prev', 'collection', 'rkey'];
+/** The twin of `signedRecordEnvelopeSchema`: v2 requires the chain fields, v1 forbids them. */
+export const signedRecordEnvelopeCheck = exact()(refineAt(object({
+    version: union(literal(1), literal(2)),
+    type: string(minLength(1)),
+    subject: string(),
+    issuer: string(),
+    record: unknownRecord,
+    issuedAt: number(),
+    seq: optional(number(int, nonnegative)),
+    prev: optional(nullable(string())),
+    collection: optional(string(minLength(1))),
+    rkey: optional(string(minLength(1))),
+    publicKey: string(),
+    alg: literal('ES256K-DER-SHA256'),
+    signature: string(),
+}), (env) => {
+    if (env.version === 2) {
+        if (typeof env.seq !== 'number')
+            return { path: ['seq'], message: 'v2 envelope requires `seq`' };
+        if (env.prev === undefined) {
+            return { path: ['prev'], message: 'v2 envelope requires `prev` (use `null` at genesis)' };
+        }
+        if (typeof env.collection !== 'string') {
+            return { path: ['collection'], message: 'v2 envelope requires `collection`' };
+        }
+        if (typeof env.rkey !== 'string') {
+            return { path: ['rkey'], message: 'v2 envelope requires `rkey`' };
+        }
+        return undefined;
+    }
+    const carried = CHAIN_FIELDS.find((field) => env[field] !== undefined);
+    return carried
+        ? { path: [carried], message: `v1 envelope must not carry \`${carried}\`` }
+        : undefined;
+}));

package/dist/esm/client/identityLink.js

@@ -0,0 +1,50 @@
+/**
+ * Identity-link constants, QR payload and response checks, without Zod. Schemas: `../identityLink.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+import { exact, int, minLength, nullable, number, object, oneOf, pattern, positive, startsWith, string, trim, } from './check.js';
+export const IDENTITY_LINK_STATUSES = ['pending', 'signed', 'completed', 'cancelled'];
+/** The scheme and host Commons routes a link QR to. */
+export const IDENTITY_LINK_QR_PREFIX = 'oxycommons://link';
+export const LINK_ID = /^[0-9a-f]{32}$/;
+export const CHALLENGE = /^[0-9a-f]{64}$/;
+/** The QR auth.oxy.so shows: the request's id and the challenge Commons signs. */
+export function buildIdentityLinkQrPayload(linkId, challenge) {
+    return `${IDENTITY_LINK_QR_PREFIX}?id=${linkId}&c=${challenge}`;
+}
+/** The request a scanned code names, or `null` for anything that is not a link QR. */
+export function parseIdentityLinkQrPayload(raw) {
+    const value = raw.trim();
+    if (!value.startsWith(`${IDENTITY_LINK_QR_PREFIX}?`))
+        return null;
+    // Parsed by hand: React Native's `URLSearchParams` does not implement `get`.
+    const params = new Map();
+    for (const pair of value.slice(IDENTITY_LINK_QR_PREFIX.length + 1).split('&')) {
+        const separator = pair.indexOf('=');
+        if (separator > 0)
+            params.set(pair.slice(0, separator), pair.slice(separator + 1));
+    }
+    const linkId = params.get('id') ?? '';
+    const challenge = params.get('c') ?? '';
+    if (!LINK_ID.test(linkId) || !CHALLENGE.test(challenge))
+        return null;
+    return { linkId, challenge };
+}
+/* -------------------------------------------------------------------------- */
+/*  Checks                                                                    */
+/* -------------------------------------------------------------------------- */
+export const identityLinkCreateResponseCheck = exact()(object({
+    linkId: string(trim, pattern(LINK_ID, 'linkId must be 32 lowercase hex characters')),
+    challenge: string(pattern(CHALLENGE)),
+    expiresAt: number(int, positive),
+    qrPayload: string(startsWith(IDENTITY_LINK_QR_PREFIX)),
+}));
+export const identityLinkStateCheck = exact()(object({
+    status: oneOf(IDENTITY_LINK_STATUSES),
+    userId: string(minLength(1)),
+    username: nullable(string()),
+    publicKey: nullable(string()),
+    audience: string(minLength(1)),
+    expiresAt: number(int, positive),
+}));