@fora-protocol/sdk 1.0.3

package/sdk/ts/src/crossfield.js

@@ -0,0 +1,215 @@
+import { z } from "zod";
+import { GetAccountStatusResponseSchema, LicenseSchema, LicenseTermSchema, ObligationSchema, PricingSchema, RegistrationFailureSchema, RestrictionSchema, WellKnownManifestSchema, } from "../../../gen/ts/wire/schemas.js";
+function asObj(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v) ? v : undefined;
+}
+/** Read a field by its snake_case name (the only wire naming). */
+function field(o, ...names) {
+    for (const n of names) {
+        if (o[n] !== undefined)
+            return o[n];
+    }
+    return undefined;
+}
+function str(v) {
+    return typeof v === "string" ? v : "";
+}
+// ---- generated enum members (reused, not forked) --------------------------
+const OBLIGATION_KIND_SHARE_ALIKE = "OBLIGATION_KIND_SHARE_ALIKE";
+const TERM_SEMANTICS_REFERENCE_ONLY = "TERM_SEMANTICS_REFERENCE_ONLY";
+const REGISTRATION_FAILURE_INVALID_DATA = "REGISTRATION_FAILURE_REASON_INVALID_REGISTRATION_DATA";
+const PRICING_MODEL_FREE = "PRICING_MODEL_FREE";
+const PRICING_MODEL_PER_UNIT = "PRICING_MODEL_PER_UNIT";
+/**
+ * LicenseTerm.restrictions max_items. The one-per-kind rule stays silent above it,
+ * matching the contract — see licenseTermRules.
+ */
+const MAX_RESTRICTIONS = 8;
+// ---- per-message cross-field predicates -----------------------------------
+// Each returns the rule-ids VIOLATED by the instance (empty => passes). The
+// boolean expression mirrors the CEL predicate; a rule-id is emitted when the
+// CEL predicate is FALSE (protovalidate rejects when the expression is false).
+/** License.digest_required_with_uri: `this.uri == '' || this.uri_digest != ''`. */
+function licenseRules(o) {
+    const uri = str(field(o, "uri"));
+    // uri_digest is a string field; the shared valid instance also models a
+    // present digest as a `digest` object — both count as "digest present".
+    const uriDigest = str(field(o, "uri_digest"));
+    const digestObj = asObj(field(o, "digest"));
+    const hasDigest = uriDigest !== "" || digestObj !== undefined;
+    if (uri !== "" && !hasDigest)
+        return ["license.digest_required_with_uri"];
+    return [];
+}
+/**
+ * LicenseTerm rules:
+ *  - reference_only.requires_uri:
+ *    `this.semantics != REFERENCE_ONLY || (has(this.license) && this.license.uri != '')`
+ *  - one_restriction_per_kind:
+ *    `this.restrictions.size() > 8 || this.restrictions.all(r, this.restrictions.filter(o, o.kind == r.kind).size() <= 1)`
+ *
+ * The size test in the second rule is part of its meaning, not a detail of how the
+ * contract evaluates it: a list longer than the cap is refused by the cap, and this
+ * rule stays silent about it so the reported fault is the length. Mirroring it here
+ * is what keeps this face's verdict equal to the wire's on such a list.
+ */
+function licenseTermRules(o) {
+    const out = [];
+    const semantics = str(field(o, "semantics"));
+    if (semantics === TERM_SEMANTICS_REFERENCE_ONLY) {
+        const license = asObj(field(o, "license"));
+        if (!license || str(field(license, "uri")) === "") {
+            out.push("license_term.reference_only.requires_uri");
+        }
+    }
+    const restrictions = field(o, "restrictions");
+    if (Array.isArray(restrictions) && restrictions.length <= MAX_RESTRICTIONS) {
+        const kinds = restrictions.map((r) => str(field(asObj(r) ?? {}, "kind")));
+        const seen = new Set();
+        let dup = false;
+        for (const k of kinds) {
+            if (seen.has(k))
+                dup = true;
+            seen.add(k);
+        }
+        if (dup)
+            out.push("license_term.one_restriction_per_kind");
+    }
+    return out;
+}
+/**
+ * Obligation.share_alike.requires_scope_license:
+ * `this.kind != SHARE_ALIKE || (has(this.scope_license) && (this.scope_license.id != '' || this.scope_license.uri != ''))`.
+ */
+function obligationRules(o) {
+    if (str(field(o, "kind")) !== OBLIGATION_KIND_SHARE_ALIKE)
+        return [];
+    const raw = field(o, "scope_license");
+    // scope_license is a License (object with id/uri); a bare non-empty string is
+    // also accepted as an identifying id (the CEL's `id != ''` intent).
+    const identified = (typeof raw === "string" && raw !== "") ||
+        (asObj(raw) !== undefined &&
+            (str(field(asObj(raw), "id")) !== "" || str(field(asObj(raw), "uri")) !== ""));
+    return identified ? [] : ["obligation.share_alike.requires_scope_license"];
+}
+/**
+ * Pricing rules:
+ *  - per_unit.requires_unit: `this.model != PER_UNIT || this.unit != ''`
+ *  - free.zero_rate: `this.model != FREE || this.rate == '' || this.rate.matches('^0+([.]0+)?$')`
+ */
+function pricingRules(o) {
+    const out = [];
+    const model = str(field(o, "model"));
+    if (model === PRICING_MODEL_PER_UNIT && str(field(o, "unit")) === "") {
+        out.push("pricing.per_unit.requires_unit");
+    }
+    if (model === PRICING_MODEL_FREE) {
+        const rate = str(field(o, "rate"));
+        if (rate !== "" && !/^0+([.]0+)?$/.test(rate)) {
+            out.push("pricing.free.zero_rate");
+        }
+    }
+    return out;
+}
+/** Restriction.permitted_prohibited_disjoint: `this.permitted.all(p, !(p in this.prohibited))`. */
+function restrictionRules(o) {
+    const permitted = field(o, "permitted");
+    const prohibited = field(o, "prohibited");
+    if (!Array.isArray(permitted) || !Array.isArray(prohibited))
+        return [];
+    const banned = new Set(prohibited.map((p) => str(p)));
+    for (const p of permitted) {
+        if (banned.has(str(p)))
+            return ["restriction.permitted_prohibited_disjoint"];
+    }
+    return [];
+}
+/**
+ * WellKnownManifest.terms_digest_requires_terms_uri:
+ * `this.terms_digest == '' || this.terms_uri != ''`. A digest pins the document
+ * at terms_uri, so publishing one without the address it pins leaves nothing to
+ * check the bytes against. Mirror of the License rule above.
+ */
+function wellKnownManifestRules(o) {
+    const termsDigest = str(field(o, "terms_digest"));
+    const termsUri = str(field(o, "terms_uri"));
+    if (termsDigest !== "" && termsUri === "") {
+        return ["well_known_manifest.terms_digest_requires_terms_uri"];
+    }
+    return [];
+}
+/**
+ * GetAccountStatusResponse.terms_digest_requires_billing_ref:
+ * `this.terms_digest == '' || this.billing_ref != ''`. The digest is what this
+ * ACCOUNT accepted, so it cannot travel without the account handle it hangs on. A
+ * reader that took the digest from a response carrying no billing_ref would be
+ * reading an acceptance for an account that does not exist. Mirror of the
+ * WellKnownManifest rule above, asked of the read side.
+ */
+function getAccountStatusResponseRules(o) {
+    const termsDigest = str(field(o, "terms_digest"));
+    const billingRef = str(field(o, "billing_ref"));
+    if (termsDigest !== "" && billingRef === "") {
+        return ["get_account_status_response.terms_digest_requires_billing_ref"];
+    }
+    return [];
+}
+/**
+ * RegistrationFailure.field_errors_scoped_to_invalid_data:
+ * `this.field_errors.size() == 0 || this.reason == 6`. The member list names what
+ * failed the published schema, so any other reason carrying it publishes detail
+ * that does not apply to the refusal.
+ */
+function registrationFailureRules(o) {
+    const fieldErrors = field(o, "field_errors");
+    if (Array.isArray(fieldErrors) && fieldErrors.length > 0) {
+        if (str(field(o, "reason")) !== REGISTRATION_FAILURE_INVALID_DATA) {
+            return ["registration_failure.field_errors_scoped_to_invalid_data"];
+        }
+    }
+    return [];
+}
+const RULES_BY_MESSAGE = {
+    GetAccountStatusResponse: getAccountStatusResponseRules,
+    License: licenseRules,
+    LicenseTerm: licenseTermRules,
+    Obligation: obligationRules,
+    Pricing: pricingRules,
+    Restriction: restrictionRules,
+    RegistrationFailure: registrationFailureRules,
+    WellKnownManifest: wellKnownManifestRules,
+};
+/**
+ * crossFieldRuleIds returns the cross-field (message-CEL) rule-ids the instance
+ * violates, empty when it passes cross-field validation. Direct analogue of the
+ * Go oracle's ValidationRuleIDs(err) over the crossfield corpus.
+ */
+export function crossFieldRuleIds(message, json) {
+    const fn = RULES_BY_MESSAGE[message];
+    if (!fn)
+        throw new Error(`crossFieldRuleIds: unknown message ${message}`);
+    const o = asObj(json);
+    return o ? fn(o) : [];
+}
+function attach(schema, message) {
+    // Inside the generic, `superRefine` is typed on ZodTypeAny (Output and Input
+    // both `any`), which the compiler cannot relate to the deferred ReturnType;
+    // each exported constant below is annotated with the concrete CrossField.
+    return schema.superRefine((value, ctx) => {
+        for (const ruleId of crossFieldRuleIds(message, value)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `cross-field rule violated: ${ruleId}`,
+                params: { ruleId },
+            });
+        }
+    });
+}
+export const GetAccountStatusResponseCrossFieldSchema = attach(GetAccountStatusResponseSchema, "GetAccountStatusResponse");
+export const LicenseCrossFieldSchema = attach(LicenseSchema, "License");
+export const LicenseTermCrossFieldSchema = attach(LicenseTermSchema, "LicenseTerm");
+export const ObligationCrossFieldSchema = attach(ObligationSchema, "Obligation");
+export const PricingCrossFieldSchema = attach(PricingSchema, "Pricing");
+export const RestrictionCrossFieldSchema = attach(RestrictionSchema, "Restriction");
+export const RegistrationFailureCrossFieldSchema = attach(RegistrationFailureSchema, "RegistrationFailure");
+export const WellKnownManifestCrossFieldSchema = attach(WellKnownManifestSchema, "WellKnownManifest");

package/sdk/ts/src/endpoint-rule.d.ts

@@ -0,0 +1,30 @@
+/** Why an endpoint a manifest advertises may not be handed back, or undefined
+ * when it may.
+ *
+ * The manifest that named this endpoint is served by the very host the call is
+ * bound for, so the endpoint is only as trustworthy as that host. An Exchange may
+ * advertise itself or a subdomain of itself, on the same port, and nothing else —
+ * a dial-time address guard has no objection to an unrelated PUBLIC host, so
+ * nothing below this catches one.
+ *
+ * Userinfo is refused for a different reason with the same shape: the host
+ * comparison reads the authority's host and ignores any user:password before it,
+ * so an endpoint carrying credentials would pass the host check and then have the
+ * HTTP client stamp an Authorization header the SDK never chose, on a leg that
+ * already carries the caller's own signature.
+ *
+ * It lives in ONE place because it has two callers, and they check the same value
+ * for different reasons. The resolver checks what a manifest advertised, because
+ * that is a property of reading an endpoint out of a manifest. The client re-checks
+ * whatever its endpoint resolver handed back, because that resolver is an
+ * injectable seam and this SDK cannot make a signed call conditional on a
+ * stranger's implementation having remembered the rule. Stated twice it drifts, and
+ * a half-mirrored version of this rule is how a signed call ends up carrying
+ * credentials the SDK never chose. The Go oracle keeps it in a shared internal
+ * package for exactly this reason.
+ *
+ * Both halves are decided over ONE reading of the reference, by the shared parse
+ * in src/host-ref.ts. That is not tidiness: a value naming no scheme is a URL to
+ * one parser and a path to another, and the two answers put a credential on
+ * opposite sides of the check — "u:p@exchange.example" is where they part. */
+export declare function endpointRefusal(host: string, endpoint: string): string | undefined;

package/sdk/ts/src/endpoint-rule.js

@@ -0,0 +1,63 @@
+// The endpoint rule: whether an endpoint may be sent a signed call, given the host that
+// named it. Pure — no IO — so both the resolver that reads it out of a manifest and the
+// client that re-checks an injected resolver's answer share one statement of it.
+//
+// Deliberately not exported from the package manifest: it is the SDK's own rule, not a
+// face a consumer composes.
+import { anchoredParsed, parseRef } from "./host-ref.js";
+/** Why an endpoint a manifest advertises may not be handed back, or undefined
+ * when it may.
+ *
+ * The manifest that named this endpoint is served by the very host the call is
+ * bound for, so the endpoint is only as trustworthy as that host. An Exchange may
+ * advertise itself or a subdomain of itself, on the same port, and nothing else —
+ * a dial-time address guard has no objection to an unrelated PUBLIC host, so
+ * nothing below this catches one.
+ *
+ * Userinfo is refused for a different reason with the same shape: the host
+ * comparison reads the authority's host and ignores any user:password before it,
+ * so an endpoint carrying credentials would pass the host check and then have the
+ * HTTP client stamp an Authorization header the SDK never chose, on a leg that
+ * already carries the caller's own signature.
+ *
+ * It lives in ONE place because it has two callers, and they check the same value
+ * for different reasons. The resolver checks what a manifest advertised, because
+ * that is a property of reading an endpoint out of a manifest. The client re-checks
+ * whatever its endpoint resolver handed back, because that resolver is an
+ * injectable seam and this SDK cannot make a signed call conditional on a
+ * stranger's implementation having remembered the rule. Stated twice it drifts, and
+ * a half-mirrored version of this rule is how a signed call ends up carrying
+ * credentials the SDK never chose. The Go oracle keeps it in a shared internal
+ * package for exactly this reason.
+ *
+ * Both halves are decided over ONE reading of the reference, by the shared parse
+ * in src/host-ref.ts. That is not tidiness: a value naming no scheme is a URL to
+ * one parser and a path to another, and the two answers put a credential on
+ * opposite sides of the check — "u:p@exchange.example" is where they part. */
+export function endpointRefusal(host, endpoint) {
+    let advertised;
+    try {
+        advertised = parseRef(endpoint);
+    }
+    catch (err) {
+        // The error already names the reference, with any credential redacted. Echoing
+        // the raw endpoint alongside it would put the credential straight back — which
+        // is what happened when this branch moved ahead of the userinfo refusal below.
+        return `host=${JSON.stringify(host)}: ${String(err)}`;
+    }
+    if (advertised.hasUserinfo) {
+        // Deliberately does not echo the endpoint: it carries the credential.
+        return `host=${JSON.stringify(host)} advertises an endpoint carrying userinfo`;
+    }
+    let served;
+    try {
+        served = parseRef(host);
+    }
+    catch (err) {
+        return `the serving host is unusable: ${String(err)}`;
+    }
+    if (!anchoredParsed(served, advertised)) {
+        return `host=${JSON.stringify(host)} advertises endpoint ${JSON.stringify(endpoint)} on a different host`;
+    }
+    return undefined;
+}

package/sdk/ts/src/errordetail.d.ts

@@ -0,0 +1,115 @@
+import type { z } from "zod";
+import type { CatalogRejectionReasonSchema, DenialReasonSchema, DisputeFailureReasonSchema, DomainVerificationFailureReasonSchema, RegistrationFailureReasonSchema, RetrievalAuthFailureReasonSchema, UsageReportRejectionReasonSchema } from "../../../gen/ts/wire/schemas.ts";
+import { ErrorDetailSchema } from "../../../gen/ts/wire/schemas.ts";
+export type ErrorDetail = z.infer<typeof ErrorDetailSchema>;
+/** The fully-qualified proto name Connect stamps on an ErrorDetail transport detail. */
+export declare const ERROR_DETAIL_TYPE = "fora.v1.ErrorDetail";
+/**
+ * The ErrorDetail `reason` oneof members, in proto field-number order (the same
+ * order the Go helpers.Reason accessor walks). Exactly one is populated when a
+ * typed reason is present; all are absent for a generic transport-class failure.
+ */
+export declare const REASON_FIELDS: readonly ["transaction_denial", "catalog_rejection", "registration_failure", "dispute_failure", "domain_verification_failure", "retrieval_auth_failure", "usage_report_rejection"];
+export type ReasonField = (typeof REASON_FIELDS)[number];
+/** The extracted typed reason: which oneof family fired, and its enum NAME. */
+export interface TypedReason {
+    field: ReasonField;
+    value: string;
+}
+/**
+ * Parse a canonical proto-JSON ErrorDetail object into the generated model. The
+ * payload is the proto-JSON object (snake_case keys, enums as NAME strings). This
+ * is the low-level decode the corpus replay exercises and the building block of
+ * {@link errorDetailFrom}.
+ */
+export declare function parseErrorDetail(payload: unknown): ErrorDetail;
+/**
+ * Return the active typed reason (oneof family + enum NAME), or null when no reason
+ * is set. Mirrors the Go helpers.Reason accessor so callers branch on the family +
+ * value, never on the human message string.
+ */
+export declare function reason(detail: ErrorDetail): TypedReason | null;
+/**
+ * Extract the first FORA ErrorDetail from a Connect error (or its details array).
+ * `err` is either a Connect error object (carrying a `details` array) or the
+ * details iterable itself. Each detail entry is the Connect wire form
+ * `{ "type": "fora.v1.ErrorDetail", ... }`; the ErrorDetail proto-JSON is read from
+ * the entry's `debug` projection (Connect includes it for JSON clients) or from a
+ * `value` already decoded to an object. Returns null when `err` carries no
+ * ErrorDetail — the TS analog of the Go `(detail, false)`.
+ *
+ * The opaque binary `value` of a detail is intentionally NOT decoded here: the JSON
+ * SDKs have no protobuf binary codec, so they consume the proto-JSON form.
+ *
+ * Both payload forms are read through protoNames, because `debug` arrives
+ * lowerCamelCase and a decoded `value` — which only a caller that owns a binary codec
+ * can supply — may be either. A snake_case object passes through it unchanged.
+ */
+export declare function errorDetailFrom(err: unknown): ErrorDetail | null;
+/** ExecuteTransaction denial reason (the DenialReason enum NAME set). */
+export type DenialReason = z.infer<typeof DenialReasonSchema>;
+/** Signed-URL / proof-of-possession failure reason. */
+export type RetrievalAuthFailureReason = z.infer<typeof RetrievalAuthFailureReasonSchema>;
+/** CatalogService rejection reason. */
+export type CatalogRejectionReason = z.infer<typeof CatalogRejectionReasonSchema>;
+/** Agent/provider registration failure reason. */
+export type RegistrationFailureReason = z.infer<typeof RegistrationFailureReasonSchema>;
+/** DisputeTransaction filing failure reason. */
+export type DisputeFailureReason = z.infer<typeof DisputeFailureReasonSchema>;
+/** Domain-verification failure reason. */
+export type DomainVerificationFailureReason = z.infer<typeof DomainVerificationFailureReasonSchema>;
+/** ReportUsage rejection reason. */
+export type UsageReportRejectionReason = z.infer<typeof UsageReportRejectionReasonSchema>;
+/**
+ * Build an ErrorDetail carrying a typed DenialReason (ExecuteTransaction denial).
+ * TS peer of Go `helpers.TransactionDenialDetail`. Sets only the `transaction_denial`
+ * reason block; the message's extra sub-fields (offer_id, restriction_mismatches) and
+ * metadata are omitted — mutate the returned object post-construction if needed.
+ */
+export declare function transactionDenialDetail(domain: string, message: string, reason: DenialReason): ErrorDetail;
+/**
+ * Build an ErrorDetail carrying a typed RetrievalAuthFailureReason.
+ * TS peer of Go `helpers.RetrievalAuthFailureDetail` (signed-URL / proof-of-possession
+ * check failed).
+ */
+export declare function retrievalAuthFailureDetail(domain: string, message: string, reason: RetrievalAuthFailureReason): ErrorDetail;
+/**
+ * Build an ErrorDetail carrying a typed CatalogRejectionReason.
+ * TS peer of Go `helpers.CatalogRejectionDetail`. Sets only the `catalog_rejection`
+ * reason block; `rejected_paths` is omitted.
+ */
+export declare function catalogRejectionDetail(domain: string, message: string, reason: CatalogRejectionReason): ErrorDetail;
+/** One offending `registration_data` member on a schema-enforcement refusal. */
+export type RegistrationFieldError = {
+    /** RFC 6901 JSON Pointer relative to `registration_data`; "" is the whole object. */
+    path: string;
+    /** Non-authoritative description of what failed; states the constraint, never the value. */
+    error: string;
+};
+/**
+ * Build an ErrorDetail carrying a typed RegistrationFailureReason.
+ * TS peer of Go `helpers.RegistrationFailureDetail` (agent/provider registration
+ * refused).
+ *
+ * `fieldErrors` carries the offending `registration_data` members when the reason
+ * is `REGISTRATION_FAILURE_REASON_INVALID_REGISTRATION_DATA`. It is optional
+ * rather than positional so the six reasons that carry no per-member detail keep
+ * the three-argument call, matching Go's variadic. Passing it with any other
+ * reason is a caller error — the field's contract says the list is empty then.
+ */
+export declare function registrationFailureDetail(domain: string, message: string, reason: RegistrationFailureReason, fieldErrors?: readonly RegistrationFieldError[]): ErrorDetail;
+/**
+ * Build an ErrorDetail carrying a typed DisputeFailureReason.
+ * TS peer of Go `helpers.DisputeFailureDetail` (DisputeTransaction filing refused).
+ */
+export declare function disputeFailureDetail(domain: string, message: string, reason: DisputeFailureReason): ErrorDetail;
+/**
+ * Build an ErrorDetail carrying a typed DomainVerificationFailureReason.
+ * TS peer of Go `helpers.DomainVerificationFailureDetail` (domain verification failed).
+ */
+export declare function domainVerificationFailureDetail(domain: string, message: string, reason: DomainVerificationFailureReason): ErrorDetail;
+/**
+ * Build an ErrorDetail carrying a typed UsageReportRejectionReason.
+ * TS peer of Go `helpers.UsageReportRejectionDetail` (ReportUsage filing rejected).
+ */
+export declare function usageReportRejectionDetail(domain: string, message: string, reason: UsageReportRejectionReason): ErrorDetail;