@ixo/openhands-sdk 0.0.0-stage → 0.1.0

package/dist/esm/udid/resolve.js

@@ -0,0 +1,162 @@
+/**
+ * Whose key signed this, asked of whoever signed it.
+ *
+ * A verifier configured with one issuer's address can check that issuer and
+ * nobody else — which is fine until somebody else's oracle rules on one of
+ * your claims, and then every surface you own quietly fails to read a
+ * perfectly valid verdict. So resolution starts from the determination's own
+ * `iss` and dispatches by DID method.
+ *
+ * Two methods matter today, and they agree on nothing:
+ *
+ *   did:ixo:<address>  the chain's resolver · Ed25519VerificationKey2018
+ *                      · publicKeyBase58                        (our checker)
+ *   did:web:<domain>   https://<domain>/.well-known/did.json
+ *                      · Ed25519VerificationKey2020
+ *                      · publicKeyMultibase (z6Mk…)      (ixo's evals engine)
+ *
+ * **`assertionMethod` only.** A DID document may carry Ed25519 keys for other
+ * jobs — a UCAN key for capability tokens is one, and the engine's own chain
+ * identity carries exactly that shape. A key minted to sign a capability must
+ * never pass as one that signs verdicts, and the document already says which
+ * is which.
+ */
+import { fromBase58 } from "./base58.js";
+import { network as configuredNetwork } from "../network.js";
+const RESOLVERS = {
+    testnet: "https://resolver.testnet.ixo.earth/1.0/identifiers",
+    devnet: "https://resolver.devnet.ixo.earth/1.0/identifiers",
+    mainnet: "https://resolver.ixo.world/1.0/identifiers"
+};
+/** base58btc → bytes, minus the two-byte `ed25519-pub` multicodec prefix. */
+export function fromMultibase(text) {
+    if (!text.startsWith("z"))
+        return null;
+    let raw;
+    try {
+        raw = fromBase58(text.slice(1));
+    }
+    catch {
+        return null;
+    }
+    return raw[0] === 0xed && raw[1] === 0x01 ? raw.slice(2) : null;
+}
+/**
+ * The asserting Ed25519 keys of a DID document, whatever shape it wrote them
+ * in. Pure — the caller fetches, so this is testable without a network.
+ */
+export function assertingKeys(document) {
+    /* A relationship entry may be a relative DID URL (`#keys-1`) — did:web
+       documents commonly write them that way — which names the same method as
+       `<document id>#keys-1`. Both forms are read; neither is guessed at when
+       the document carries no id to resolve against. */
+    const absolute = (id) => (id.startsWith("#") && document?.id ? `${document.id}${id}` : id);
+    const asserting = new Set((document?.assertionMethod ?? [])
+        .map((one) => (typeof one === "string" ? one : (one?.id ?? "")))
+        .filter(Boolean)
+        .map(absolute));
+    const out = [];
+    for (const method of document?.verificationMethod ?? []) {
+        if (!asserting.has(absolute(method.id)))
+            continue;
+        if (method.type === "Ed25519VerificationKey2018" && method.publicKeyBase58) {
+            try {
+                const raw = fromBase58(method.publicKeyBase58);
+                if (raw.length === 32)
+                    out.push({ id: method.id, raw, how: "Ed25519VerificationKey2018 · base58" });
+            }
+            catch {
+                /* An unreadable method is one we cannot check against. Skip it. */
+            }
+        }
+        if (method.type === "Ed25519VerificationKey2020" && method.publicKeyMultibase) {
+            const raw = fromMultibase(method.publicKeyMultibase);
+            if (raw?.length === 32)
+                out.push({ id: method.id, raw, how: "Ed25519VerificationKey2020 · multibase" });
+        }
+    }
+    return out;
+}
+const defaultFetch = async (url) => {
+    const answer = await fetch(url, { signal: AbortSignal.timeout(20_000) });
+    return answer.ok ? await answer.json() : null;
+};
+/*
+ * The shape a did:web is allowed to have before it becomes a URL.
+ *
+ * `iss` is read off a document anybody can publish, and `documentUrl` turns it
+ * into a request this server makes. Without a grammar, `did:web:a?b`,
+ * `did:web:user@host`, `did:web:host:..:..` and `did:web:169.254.169.254` are
+ * all "valid" and each one points the fetch somewhere the spec never meant —
+ * a query, a userinfo, a path walk, a metadata endpoint. So: a hostname of
+ * RFC 1123 labels whose last label is not all digits (an IP literal is not a
+ * domain), an optional percent-encoded port, and path segments of unreserved
+ * characters only. Anything else is not a did:web this resolver will fetch.
+ */
+const HOST_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i;
+const PATH_SEGMENT = /^[a-z0-9._~-]+$/i;
+function didWebUrl(did) {
+    const [host, ...path] = did.slice("did:web:".length).split(":");
+    const [hostname, port, ...more] = (host ?? "").split("%3A");
+    const labels = (hostname ?? "").split(".");
+    if (more.length > 0 || !labels.every((label) => HOST_LABEL.test(label)))
+        throw new Error(`not a did:web hostname: ${did}`);
+    if (/^\d+$/.test(labels[labels.length - 1] ?? ""))
+        throw new Error(`a did:web must name a domain, not an address: ${did}`);
+    if (port !== undefined && !/^\d{1,5}$/.test(port))
+        throw new Error(`not a did:web port: ${did}`);
+    if (!path.every((segment) => PATH_SEGMENT.test(segment) && segment !== "." && segment !== ".."))
+        throw new Error(`not a did:web path: ${did}`);
+    const origin = `https://${hostname}${port ? `:${port}` : ""}`;
+    return path.length === 0 ? `${origin}/.well-known/did.json` : `${origin}/${path.join("/")}/did.json`;
+}
+/** Where a DID's document is served. Exported so a caller can say so in a log. */
+export function documentUrl(did, network = "testnet") {
+    if (did.startsWith("did:web:"))
+        return didWebUrl(did);
+    if (did.startsWith("did:ixo:")) {
+        /* No testnet fallback for a name we do not know: "Mainnet" resolving a
+           mainnet issuer against the testnet resolver reads as "no such key",
+           which fails verification for the wrong reason (scale review D23). */
+        const resolver = RESOLVERS[network];
+        if (!resolver)
+            throw new Error(`no ixo resolver for network ${JSON.stringify(network)}; expected one of ${Object.keys(RESOLVERS).join(", ")}`);
+        return `${resolver}/${encodeURIComponent(did)}`;
+    }
+    throw new Error(`no resolver for the DID method in ${did}`);
+}
+/*
+ * One document per issuer per few minutes, per process.
+ *
+ * A credential cites up to fifty determinations and nearly all of them name
+ * the same issuer; resolving that issuer fifty times per request is fifty
+ * round trips to the resolver for one answer. Short-lived, so a rotated key
+ * is seen within minutes, and bounded, so a stream of unknown issuers cannot
+ * grow it without limit. Only the default fetch is cached — an injected
+ * reader is a test's, and a test wants what it injected.
+ */
+const DOCUMENT_TTL_MS = 5 * 60_000;
+const DOCUMENT_CACHE_MAX = 500;
+const documents = new Map();
+export async function keysFor(did, options = {}) {
+    /* Unset or empty is the documented default (testnet); `network()` refuses any
+       other value that is not a network. Only a did:ixo needs the network, so
+       a did:web still resolves under a mis-set one, as it always did. */
+    const network = options.network ?? (did.startsWith("did:ixo:") ? configuredNetwork() : "testnet");
+    const url = documentUrl(did, network);
+    const cacheable = !options.fetchJson;
+    const held = cacheable ? documents.get(url) : undefined;
+    if (held && Date.now() - held.at < DOCUMENT_TTL_MS)
+        return held.keys;
+    const read = options.fetchJson ?? defaultFetch;
+    const body = (await read(url));
+    /* The chain's resolver wraps it; did:web serves it bare. */
+    const keys = assertingKeys(body?.didDocument ?? body);
+    if (cacheable && keys.length > 0) {
+        if (documents.size >= DOCUMENT_CACHE_MAX)
+            documents.delete(documents.keys().next().value);
+        documents.set(url, { at: Date.now(), keys });
+    }
+    return keys;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/esm/udid/resolve.js.map

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

package/dist/esm/udid/schema.d.ts

@@ -0,0 +1,150 @@
+/**
+ * What a determination is allowed to say.
+ *
+ * ixo's `oracle.udid.ixo.v1` schema, mirrored in Zod so the payload is
+ * validated **before** it is signed. A payload that fails our own schema is a
+ * bug, and signing it would put that bug on chain behind a signature that
+ * makes it look deliberate.
+ *
+ * The top level is strict on purpose: an unknown key at the root is either a
+ * typo or a dialect drift, and both are worth failing loudly. Everything
+ * project-specific lives in one place — the `ixo` block — which is the escape
+ * hatch the standard reserves for exactly this.
+ */
+import { z } from "zod";
+/** The normative outcome codes. 5 is "a person should look at this". */
+export declare const OUTCOME: {
+    readonly APPROVED: 1;
+    readonly REJECTED: 2;
+    readonly DISPUTED: 3;
+    readonly INVALIDATED: 4;
+    readonly FLAGGED: 5;
+};
+/**
+ * The environment enum the standard actually defines.
+ *
+ * Two values, and neither of them is `testnet`. Everything that is not the
+ * real chain is a simulation, and a determination that says so cannot later
+ * be screenshotted as if it moved real money.
+ */
+export declare const ENV: readonly ["production", "simulation"];
+export declare const isAllowedOutBindingKey: (key: string) => boolean;
+export declare const CoinSchema: z.ZodObject<{
+    denom: z.ZodString;
+    amount: z.ZodString;
+}, z.core.$strip>;
+export declare const UdidPayloadSchema: z.ZodObject<{
+    iss: z.ZodString;
+    sub: z.ZodString;
+    aud: z.ZodString;
+    iat: z.ZodNumber;
+    jti: z.ZodString;
+    kind: z.ZodLiteral<"oracle.eval.v1">;
+    ver: z.ZodLiteral<1>;
+    sch: z.ZodLiteral<"oracle.udid.ixo.v1">;
+    act: z.ZodObject<{
+        cap: z.ZodString;
+        rub: z.ZodObject<{
+            id: z.ZodString;
+            digest: z.ZodString;
+        }, z.core.$strip>;
+        meta: z.ZodObject<{
+            env: z.ZodEnum<{
+                production: "production";
+                simulation: "simulation";
+            }>;
+            evaluator_version: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    res: z.ZodObject<{
+        outcome: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<5>]>;
+        patch: z.ZodUnion<readonly [z.ZodObject<{}, z.core.$strict>, z.ZodObject<{
+            evaluationStatus: z.ZodNumber;
+            amount: z.ZodArray<z.ZodObject<{
+                denom: z.ZodString;
+                amount: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strict>]>;
+        trace: z.ZodObject<{
+            uri: z.ZodString;
+            cid: z.ZodString;
+        }, z.core.$strip>;
+        reason: z.ZodString;
+    }, z.core.$strip>;
+    out: z.ZodObject<{
+        summary: z.ZodString;
+        bindings: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    }, z.core.$strip>;
+    ixo: z.ZodObject<{
+        cellNode: z.ZodString;
+        oracleDid: z.ZodString;
+        collectionId: z.ZodString;
+        claimId: z.ZodString;
+        entityDid: z.ZodString;
+        agentAddress: z.ZodString;
+        agentDid: z.ZodString;
+        network: z.ZodString;
+        verdict: z.ZodString;
+        reasonCode: z.ZodNumber;
+        criteria: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodString;
+            outcome: z.ZodEnum<{
+                unverifiable: "unverifiable";
+                pass: "pass";
+                fail: "fail";
+            }>;
+        }, z.core.$strip>>;
+        receipt: z.ZodString;
+    }, z.core.$catchall<z.ZodUnknown>>;
+}, z.core.$strict>;
+export type UdidPayload = z.infer<typeof UdidPayloadSchema>;
+/**
+ * What we accept from **anybody**, as opposed to what we ourselves emit.
+ *
+ * The schema above is our profile: strict, opinionated, and correct for the
+ * bytes we sign. Using it to *verify* was a mistake that only showed up when
+ * ixo's own evals engine was put beside us — it emits the same `kind` and
+ * `ver` under a different `sch`, with no `out`, no `act.meta`, and
+ * `res.trace.digest` where we write `res.trace.cid`. Every field of that is
+ * legitimate: `sch` is a profile marker over a shared base, and their schema
+ * says so in as many words.
+ *
+ * So this is the base, and only the base. Anything a determination is allowed
+ * to add rides through `passthrough`. Both our payload and the engine's
+ * validate against ixo's published `udid-payload-v1` unchanged — the base is
+ * not ours to invent, and the conformance test holds this one to it.
+ *
+ * The fields that stay required are the ones a verifier cannot do without:
+ * who signed, about what, in what scope, when, and what was decided.
+ */
+export declare const UdidBaseSchema: z.ZodObject<{
+    iss: z.ZodString;
+    sub: z.ZodString;
+    aud: z.ZodString;
+    iat: z.ZodNumber;
+    jti: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"oracle.eval.v1">;
+    ver: z.ZodLiteral<1>;
+    sch: z.ZodOptional<z.ZodString>;
+    act: z.ZodObject<{
+        cap: z.ZodString;
+        rub: z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$loose>;
+    }, z.core.$loose>;
+    res: z.ZodObject<{
+        outcome: z.ZodNumber;
+        patch: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        trace: z.ZodOptional<z.ZodObject<{
+            uri: z.ZodString;
+        }, z.core.$loose>>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    out: z.ZodOptional<z.ZodObject<{
+        summary: z.ZodString;
+    }, z.core.$loose>>;
+    ixo: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>;
+export type UdidBase = z.infer<typeof UdidBaseSchema>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/esm/udid/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/udid/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,wEAAwE;AACxE,eAAO,MAAM,OAAO;;;;;;CAAiF,CAAC;AAEtG;;;;;;GAMG;AACH,eAAO,MAAM,GAAG,uCAAwC,CAAC;AAczD,eAAO,MAAM,sBAAsB,GAAI,KAAK,MAAM,KAAG,OAAgC,CAAC;AAEtF,eAAO,MAAM,UAAU;;;iBAA4E,CAAC;AAEpG,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAgE1B,CAAC;AAEL,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4BX,CAAC;AAEjB,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/esm/udid/schema.js

@@ -0,0 +1,151 @@
+/**
+ * What a determination is allowed to say.
+ *
+ * ixo's `oracle.udid.ixo.v1` schema, mirrored in Zod so the payload is
+ * validated **before** it is signed. A payload that fails our own schema is a
+ * bug, and signing it would put that bug on chain behind a signature that
+ * makes it look deliberate.
+ *
+ * The top level is strict on purpose: an unknown key at the root is either a
+ * typo or a dialect drift, and both are worth failing loudly. Everything
+ * project-specific lives in one place — the `ixo` block — which is the escape
+ * hatch the standard reserves for exactly this.
+ */
+import { z } from "zod";
+/** The normative outcome codes. 5 is "a person should look at this". */
+export const OUTCOME = { APPROVED: 1, REJECTED: 2, DISPUTED: 3, INVALIDATED: 4, FLAGGED: 5 };
+/**
+ * The environment enum the standard actually defines.
+ *
+ * Two values, and neither of them is `testnet`. Everything that is not the
+ * real chain is a simulation, and a determination that says so cannot later
+ * be screenshotted as if it moved real money.
+ */
+export const ENV = ["production", "simulation"];
+const CriterionOutcome = z.enum(["pass", "fail", "unverifiable"]);
+/**
+ * What `out.bindings` may name.
+ *
+ * `sub`, or a dotted path under `res` — and nothing else. `out` is narrative;
+ * bindings exist so a reader can check that the narrative echoes the result
+ * rather than asserting anything of its own. Letting it point at `act.cap` or
+ * `iat` would make the prose load-bearing, which is exactly what the standard
+ * is written to prevent. The pattern is ixo's own, character for character.
+ */
+const OUT_BINDING = /^(sub|res(\.[a-zA-Z0-9_]+)+)$/;
+export const isAllowedOutBindingKey = (key) => OUT_BINDING.test(key);
+export const CoinSchema = z.object({ denom: z.string().min(1), amount: z.string().regex(/^\d+$/) });
+export const UdidPayloadSchema = z
+    .object({
+    iss: z.string().min(1),
+    sub: z.string().min(1),
+    /** Replay-proof scope. Anything the verifier can pin an expectation to. */
+    aud: z.string().min(1),
+    iat: z.number().int().positive(),
+    jti: z.string().min(1),
+    kind: z.literal("oracle.eval.v1"),
+    ver: z.literal(1),
+    sch: z.literal("oracle.udid.ixo.v1"),
+    act: z.object({
+        /** Who authorised this evaluation — the ask's entity. */
+        cap: z.string().min(1),
+        rub: z.object({ id: z.string().min(1), digest: z.string().min(1) }),
+        meta: z.object({ env: z.enum(ENV), evaluator_version: z.string().min(1) })
+    }),
+    res: z.object({
+        outcome: z.union([z.literal(1), z.literal(2), z.literal(3), z.literal(4), z.literal(5)]),
+        /** What the chain was asked to write. Empty when nothing was decided. */
+        patch: z.union([
+            z.object({}).strict(),
+            z.object({ evaluationStatus: z.number().int(), amount: z.array(CoinSchema) }).strict()
+        ]),
+        trace: z.object({ uri: z.string().url(), cid: z.string().min(1) }),
+        reason: z.string().min(1)
+    }),
+    out: z.object({
+        summary: z.string().min(1),
+        bindings: z.record(z.string(), z.union([z.string(), z.number()]))
+    }),
+    ixo: z
+        .object({
+        /* The origin the receipt was published to; the key keeps its old name
+           because every verifier of this schema reads `ixo.cellNode`. */
+        cellNode: z.string().url(),
+        oracleDid: z.string().min(1),
+        collectionId: z.string().min(1),
+        claimId: z.string().min(1),
+        entityDid: z.string().min(1),
+        agentAddress: z.string().min(1),
+        agentDid: z.string().min(1),
+        network: z.string().min(1),
+        verdict: z.string().min(1),
+        reasonCode: z.number().int(),
+        criteria: z.array(z.object({ id: z.string(), kind: z.string(), outcome: CriterionOutcome })),
+        receipt: z.string().min(1)
+    })
+        /* The block the standard reserves for the project. Open, because a
+           campaign carries its own words here and this file must not become
+           the thing you edit to add one. */
+        .catchall(z.unknown())
+})
+    .strict()
+    .superRefine((payload, ctx) => {
+    for (const key of Object.keys(payload.out.bindings)) {
+        if (!isAllowedOutBindingKey(key)) {
+            ctx.addIssue({ code: "custom", path: ["out", "bindings", key], message: `out.bindings may not name ${key}` });
+        }
+    }
+    /* Flagged decides nothing, so it must not carry a patch that says it did. */
+    if (payload.res.outcome === OUTCOME.FLAGGED && Object.keys(payload.res.patch).length > 0) {
+        ctx.addIssue({ code: "custom", path: ["res", "patch"], message: "a flagged determination patches nothing" });
+    }
+});
+/**
+ * What we accept from **anybody**, as opposed to what we ourselves emit.
+ *
+ * The schema above is our profile: strict, opinionated, and correct for the
+ * bytes we sign. Using it to *verify* was a mistake that only showed up when
+ * ixo's own evals engine was put beside us — it emits the same `kind` and
+ * `ver` under a different `sch`, with no `out`, no `act.meta`, and
+ * `res.trace.digest` where we write `res.trace.cid`. Every field of that is
+ * legitimate: `sch` is a profile marker over a shared base, and their schema
+ * says so in as many words.
+ *
+ * So this is the base, and only the base. Anything a determination is allowed
+ * to add rides through `passthrough`. Both our payload and the engine's
+ * validate against ixo's published `udid-payload-v1` unchanged — the base is
+ * not ours to invent, and the conformance test holds this one to it.
+ *
+ * The fields that stay required are the ones a verifier cannot do without:
+ * who signed, about what, in what scope, when, and what was decided.
+ */
+export const UdidBaseSchema = z
+    .object({
+    iss: z.string().min(1),
+    sub: z.string().min(1),
+    aud: z.string().min(1),
+    iat: z.number().int().positive(),
+    jti: z.string().min(1).optional(),
+    kind: z.literal("oracle.eval.v1"),
+    ver: z.literal(1),
+    /** A profile marker, not a gate. We read it; we never require our own. */
+    sch: z.string().min(1).optional(),
+    act: z
+        .object({
+        cap: z.string().min(1),
+        rub: z.object({ id: z.string().min(1) }).passthrough()
+    })
+        .passthrough(),
+    res: z
+        .object({
+        outcome: z.number().int().min(0).max(5),
+        patch: z.record(z.string(), z.unknown()),
+        trace: z.object({ uri: z.string().min(1) }).passthrough().optional(),
+        reason: z.string().min(1).optional()
+    })
+        .passthrough(),
+    out: z.object({ summary: z.string().min(1) }).passthrough().optional(),
+    ixo: z.record(z.string(), z.unknown()).optional()
+})
+    .passthrough();
+//# sourceMappingURL=schema.js.map

package/dist/esm/udid/schema.js.map

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

package/dist/esm/udid/verify.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Checking a determination without asking us anything.
+ *
+ * The point of signing is that this can run somewhere we do not control,
+ * against a key published somewhere anyone can read. So the checks are the
+ * blunt ones and they are all of them: the signature is real, the payload is
+ * the shape the standard defines, and it is about the thing the reader
+ * thinks it is about.
+ *
+ * **`aud` is not decoration.** A determination lifted from one collection and
+ * replayed against another verifies perfectly by signature alone; pinning
+ * `expectedAud` is what makes that a forgery rather than a fact.
+ */
+import { type UdidBase } from "./schema.ts";
+declare const fromB64url: (text: string) => Uint8Array;
+export interface VerifyOptions {
+    /** The 32-byte public point of the issuer, however the reader resolved it. */
+    publicKeyRaw: Uint8Array;
+    expectedAud?: string;
+    expectedSub?: string;
+    /** The address the wrapper claims these bytes have. */
+    expectedCid?: string;
+    /** Seconds since the epoch, for the `exp` check. Defaults to the clock. */
+    now?: number;
+}
+export interface VerifyResult {
+    valid: boolean;
+    /** The **base** payload — anyone's, not only ours. See `UdidBaseSchema`. */
+    payload: UdidBase | null;
+    /** Why not, in one phrase — for a log or a page, never for a decision. */
+    reason?: string;
+}
+export declare function verifyUdid(jws: string, options: VerifyOptions): Promise<VerifyResult>;
+export { fromB64url };
+//# sourceMappingURL=verify.d.ts.map

package/dist/esm/udid/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/udid/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5D,QAAA,MAAM,UAAU,GAAI,MAAM,MAAM,KAAG,UAGlC,CAAC;AAgBF,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,YAAY,EAAE,UAAU,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,OAAO,CAAC;IACf,4EAA4E;IAC5E,OAAO,EAAE,QAAQ,GAAG,IAAI,CAAC;IACzB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CA2D3F;AAED,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/dist/esm/udid/verify.js

@@ -0,0 +1,93 @@
+/**
+ * Checking a determination without asking us anything.
+ *
+ * The point of signing is that this can run somewhere we do not control,
+ * against a key published somewhere anyone can read. So the checks are the
+ * blunt ones and they are all of them: the signature is real, the payload is
+ * the shape the standard defines, and it is about the thing the reader
+ * thinks it is about.
+ *
+ * **`aud` is not decoration.** A determination lifted from one collection and
+ * replayed against another verifies perfectly by signature alone; pinning
+ * `expectedAud` is what makes that a forgery rather than a fact.
+ */
+import { canonicalJson } from "./canonical.js";
+import { cidV1Raw } from "./cid.js";
+import { UdidBaseSchema } from "./schema.js";
+const fromB64url = (text) => {
+    const padded = text.replace(/-/g, "+").replace(/_/g, "/");
+    return Uint8Array.from(atob(padded + "=".repeat((4 - (padded.length % 4)) % 4)), (c) => c.charCodeAt(0));
+};
+/**
+ * A compact JWS segment is base64url with no padding and nothing else.
+ *
+ * `atob` is forgiving — it skips ASCII whitespace and tolerates padding — so
+ * without this check two different strings could decode to the same bytes,
+ * verify against the same signature, and carry two different content
+ * addresses. The address is the whole point of `expectedCid`, so the string
+ * has to be exactly one encoding of the bytes it names.
+ */
+const B64URL = /^[A-Za-z0-9_-]+$/;
+/** An Ed25519 signature is exactly 64 bytes; anything else is not one. */
+const ED25519_SIGNATURE_BYTES = 64;
+export async function verifyUdid(jws, options) {
+    const parts = jws.split(".");
+    if (parts.length !== 3)
+        return { valid: false, payload: null, reason: "not a compact JWS" };
+    const [header, body, signature] = parts;
+    if (!B64URL.test(header) || !B64URL.test(body) || !B64URL.test(signature)) {
+        return { valid: false, payload: null, reason: "a segment is not strict base64url" };
+    }
+    let head;
+    let payload;
+    try {
+        head = JSON.parse(new TextDecoder().decode(fromB64url(header)));
+        /* The base, never our profile — a verifier that only accepts its own
+           dialect can only ever check itself. */
+        payload = UdidBaseSchema.parse(JSON.parse(new TextDecoder().decode(fromB64url(body))));
+    }
+    catch (error) {
+        return { valid: false, payload: null, reason: error instanceof Error ? error.message : "unreadable" };
+    }
+    if (head.alg !== "EdDSA")
+        return { valid: false, payload, reason: `unexpected alg ${String(head.alg)}` };
+    /* RFC 7515 §4.1.11: a `crit` header names extensions the verifier MUST
+       understand. This verifier understands none, so any `crit` is a refusal. */
+    if (head.crit !== undefined)
+        return { valid: false, payload, reason: "header names critical extensions this verifier does not implement" };
+    const signatureBytes = fromB64url(signature);
+    if (signatureBytes.length !== ED25519_SIGNATURE_BYTES)
+        return { valid: false, payload, reason: "signature is not 64 bytes" };
+    const key = await crypto.subtle.importKey("raw", options.publicKeyRaw, { name: "Ed25519" }, false, ["verify"]);
+    const ok = await crypto.subtle.verify({ name: "Ed25519" }, key, signatureBytes, new TextEncoder().encode(`${header}.${body}`));
+    if (!ok)
+        return { valid: false, payload, reason: "signature does not verify" };
+    if (options.expectedAud && payload.aud !== options.expectedAud)
+        return { valid: false, payload, reason: "aud is for something else" };
+    if (options.expectedSub && payload.sub !== options.expectedSub)
+        return { valid: false, payload, reason: "sub is a different claim" };
+    /* `exp` is optional in the standard, and a determination that carries one
+       has said when it stops being one. The base schema passes it through. */
+    const exp = payload.exp;
+    if (exp !== undefined) {
+        if (typeof exp !== "number" || !Number.isFinite(exp))
+            return { valid: false, payload, reason: "exp is not a number" };
+        const now = options.now ?? Math.floor(Date.now() / 1000);
+        if (exp <= now)
+            return { valid: false, payload, reason: "expired" };
+    }
+    if (options.expectedCid) {
+        const cid = await cidV1Raw(new TextEncoder().encode(jws));
+        if (cid !== options.expectedCid)
+            return { valid: false, payload, reason: "these bytes have a different address" };
+    }
+    /* The body must be the canonical form, or two readers could hold two
+       documents that both verify and differ. */
+    const canonical = canonicalJson(payload);
+    if (new TextDecoder().decode(fromB64url(body)) !== canonical) {
+        return { valid: false, payload, reason: "payload is not in canonical form" };
+    }
+    return { valid: true, payload };
+}
+export { fromB64url };
+//# sourceMappingURL=verify.js.map

package/dist/esm/udid/verify.js.map

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