@multiagency/sdk 0.3.1

package/dist/contract/app-access.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { AppScope } from "./app-consent.js";
+/**
+ * What an app deployment may do through `/apps/v1`: the gateway enforces with these same definitions, and
+ * the app client is typed by them. Presenting never authorizes.
+ */
+/** Reads the app may make with `read` consent. Workflow records (agreements, invoices, work orders) stay out. */
+export const APP_READS = ["instance", "overview", "policyHistory", "activity", "unresolved", "held", "ledger", "ledgerCsv",
+    "owner/actions", "owner/pending", "owner/status", "paymentHistory", "paymentStatus"];
+/** Owner actions with `owner` consent: prepared here, completed only by the owner's own wallet signature at submit. */
+export const APP_OWNER = ["owner/prepare", "owner/submit", "owner/status", "owner/pending", "owner/actions"];
+/**
+ * Payout requests with `payout` consent: each sent at most once under the app's `requestId`, within the owner-signed
+ * policy, and held for the owner's vote when the policy says so. `held` shows what waits for that vote. `deposit` gives a
+ * one-time address that credits USDC, or wNEAR, to the agent's confidential balance, so the app can fund it; it moves
+ * nothing out.
+ */
+export const APP_PAYOUT = ["payouts/request", "payouts/status", "held", "deposit"];
+const READS = new Set(APP_READS), OWNER = new Set(APP_OWNER), PAYOUT = new Set(APP_PAYOUT);
+/** Whether consent scopes cover a procedure (the gateway also requires the owner's own access to it). */
+export const appScopesCover = (scopes, path) => (scopes.includes("read") && READS.has(path)) || (scopes.includes("owner") && OWNER.has(path)) || (scopes.includes("payout") && PAYOUT.has(path));
+/**
+ * What the app may ask an owner to sign. The app chooses what it asks for, but never what the owner reads: a prepared
+ * intent reaches the app only when it is NEP-413, whose text the owner's wallet shows. A NEP-366 intent (creation,
+ * freeze, unfreeze, on-chain policy edits) is held on the platform, and the app gets a confirm page instead, where the
+ * platform shows the owner its own record of the action and the owner signs; the app gets those bytes only with the
+ * owner's signature over the link's text, which tells the owner in the wallet to sign it only on the platform. Payees are added after creation, not at it. A
+ * vote on a held payout is bound by the agent to that payout's provider evidence and re-authorized under the current
+ * policy, so it can release only a transfer to an agreed payee within the caps; its prepared answer carries the proven
+ * terms for the app to show.
+ */
+const APP_OWNER_ACTIONS = new Set(["agent_create", "agent_freeze", "agent_unfreeze", "grant_issue", "grant_revoke", "policy_update", "approval_vote"]);
+/** Whether a parsed owner action is one the app may prepare (signer `wallet` is checked separately). */
+export function appMayAsk(action) {
+    if (action.type === "agent_create" && action.payees?.length)
+        return false;
+    return APP_OWNER_ACTIONS.has(action.type);
+}
+/**
+ * A NEP-366 owner action the platform holds for the owner to sign on its confirm page (`/confirm/<token>`). The link
+ * shows the action's terms to whoever holds it; the bytes to sign go only to whoever presents the owner's signature over
+ * the link's text, which the page asks the owner's wallet for. Open it for the owner right away: the intent expires in minutes. Follow the outcome with
+ * `owner/status`; the app can't submit it.
+ */
+export const appConfirm = z.looseObject({ url: z.string(), expiresAt: z.string() });
+/** `GET /apps/v1/agents/<agent>`: what the owner's consent must name. */
+export const appAgent = z.looseObject({ agent: z.string(), owner: z.string(), agentId: z.string().nullable(), created: z.boolean(),
+    host: z.string(), deployment: z.string() });
+/** A stored consent as the platform shows it: never its message, nonce or signature. Times are epoch milliseconds. */
+export const appConsentView = z.looseObject({ id: z.string(), deployment: z.string(), host: z.string(), organization: z.string(),
+    owner: z.string(), agent: z.string(), agentId: z.string(), scopes: z.array(AppScope), expiresAt: z.number(), createdAt: z.number(),
+    publicKey: z.string(), revoked: z.boolean(), revokedAt: z.number().nullable() });
+export const appConsentList = z.looseObject({ consents: z.array(appConsentView) });
+export const appConsentStored = z.looseObject({ consent: appConsentView });
+/** `POST /apps/v1/setup`: the hosted agent's name and its setup consent (agent ID `unborn`). */
+export const appSetupStored = z.looseObject({ agent: z.string(), consent: appConsentView });
+export const appRevoked = z.looseObject({ revoked: z.literal(true) });

package/dist/contract/app-client.d.ts

@@ -0,0 +1,140 @@
+import type { z } from "zod";
+import { type AppOwnerAction, type AppProcedure } from "./app-access.js";
+import type { appConsentSubmission } from "./app-consent.js";
+import { type OwnerCallOptions, type OwnerOutput, type OwnerResult } from "./owner-client.js";
+import type { OwnerInputs } from "./owner-inputs.js";
+type Fetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export type AppBase = `https://${string}` | `http://${string}`;
+export type AppConsentSubmission = z.input<typeof appConsentSubmission>;
+/**
+ * An answer from the app routes (identity, setup, consents). Decided by status, never by message text.
+ * - `session` (401): the service credential is invalid, expired or revoked.
+ * - `forbidden` (403): refused for this caller (for example setup unavailable on this host, or a signer that doesn't own
+ *   the agent). Resending the same request won't change it.
+ * - `refused`: the platform refused the request as made (400 invalid or revoked text, 404, 409 conflict, 429 limit).
+ * - `unavailable`: no answer, 5xx (503: an ownership or key check went unanswered, nothing stored or forwarded), or an
+ *   unreadable one. Setup, consent submission and revocation are idempotent for the same signed body, so resending it is safe.
+ */
+export type AppRouteResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    kind: "session";
+    status: 401;
+    error: string;
+} | {
+    ok: false;
+    kind: "forbidden";
+    status: 403;
+    error: string;
+} | {
+    ok: false;
+    kind: "refused";
+    status: number;
+    error: string;
+} | {
+    ok: false;
+    kind: "unavailable";
+    httpStatus?: number;
+};
+/** Procedure inputs as an app may send them: `owner/prepare` takes only actions an app may ask an owner to sign. */
+export type AppInputs = {
+    [P in AppProcedure]: P extends "owner/prepare" ? {
+        action: AppOwnerAction;
+        signer: "wallet";
+    } : OwnerInputs[P];
+};
+/**
+ * A server-side client for an app deployment's routes under `/apps/v1` on the platform host. It adds the deployment's
+ * service credential (a server secret: never give it to a browser). Agent calls go through `ownerClient`, with its result
+ * kinds; they are typed to what app consents can reach, and the gateway enforces the same lists.
+ */
+export declare function appClient({ base, credential, fetch: send }: {
+    base: AppBase;
+    credential: string;
+    fetch?: Fetch;
+}): {
+    /** The agent's owner and current provider ID (`agentId`, null until created): what a consent must name. */
+    identity: (agent: string) => Promise<AppRouteResult<{
+        [x: string]: unknown;
+        agent: string;
+        owner: string;
+        agentId: string | null;
+        created: boolean;
+        host: string;
+        deployment: string;
+    }>>;
+    /** A wallet owner's signed setup text: reserves the hosted agent and returns its setup consent. */
+    setup: (submission: AppConsentSubmission) => Promise<AppRouteResult<{
+        [x: string]: unknown;
+        agent: string;
+        consent: {
+            [x: string]: unknown;
+            id: string;
+            deployment: string;
+            host: string;
+            organization: string;
+            owner: string;
+            agent: string;
+            agentId: string;
+            scopes: ("owner" | "payout" | "read")[];
+            expiresAt: number;
+            createdAt: number;
+            publicKey: string;
+            revoked: boolean;
+            revokedAt: number | null;
+        };
+    }>>;
+    consents: {
+        list: (organization?: string) => Promise<AppRouteResult<{
+            [x: string]: unknown;
+            consents: {
+                [x: string]: unknown;
+                id: string;
+                deployment: string;
+                host: string;
+                organization: string;
+                owner: string;
+                agent: string;
+                agentId: string;
+                scopes: ("owner" | "payout" | "read")[];
+                expiresAt: number;
+                createdAt: number;
+                publicKey: string;
+                revoked: boolean;
+                revokedAt: number | null;
+            }[];
+        }>>;
+        submit: (submission: AppConsentSubmission) => Promise<AppRouteResult<{
+            [x: string]: unknown;
+            consent: {
+                [x: string]: unknown;
+                id: string;
+                deployment: string;
+                host: string;
+                organization: string;
+                owner: string;
+                agent: string;
+                agentId: string;
+                scopes: ("owner" | "payout" | "read")[];
+                expiresAt: number;
+                createdAt: number;
+                publicKey: string;
+                revoked: boolean;
+                revokedAt: number | null;
+            };
+        }>>;
+        /** Permanent: the owner signs a new consent to restore access. */
+        revoke: (id: string) => Promise<AppRouteResult<{
+            [x: string]: unknown;
+            revoked: true;
+        }>>;
+    };
+    /** One Organization's agent: reads and owner actions its live consents cover. */
+    agent(organization: string, agent: string): {
+        call<P extends AppProcedure>(path: P, ...[input, options]: undefined extends AppInputs[P] ? [input?: AppInputs[P], options?: OwnerCallOptions] : [input: AppInputs[P], options?: OwnerCallOptions]): Promise<OwnerResult<OwnerOutput<P>>>;
+    };
+};
+export type AppClient = ReturnType<typeof appClient>;
+export {};

package/dist/contract/app-client.js

@@ -0,0 +1,61 @@
+import { appAgent, appConsentList, appConsentStored, appRevoked, appSetupStored } from "./app-access.js";
+import { ownerClient } from "./owner-client.js";
+const covered = true;
+void covered;
+/**
+ * A server-side client for an app deployment's routes under `/apps/v1` on the platform host. It adds the deployment's
+ * service credential (a server secret: never give it to a browser). Agent calls go through `ownerClient`, with its result
+ * kinds; they are typed to what app consents can reach, and the gateway enforces the same lists.
+ */
+export function appClient({ base, credential, fetch: send = globalThis.fetch }) {
+    const root = base.replace(/\/+$/, "");
+    const authorized = (input, init) => {
+        const headers = new Headers(init?.headers);
+        headers.set("authorization", `Bearer ${credential}`);
+        return send(input, { ...init, headers });
+    };
+    async function route(path, schema, init = {}) {
+        let response;
+        try {
+            response = await authorized(`${root}/apps/v1${path}`, init);
+        }
+        catch {
+            return { ok: false, kind: "unavailable" };
+        }
+        const body = await response.json().catch(() => undefined);
+        if (response.ok) {
+            const parsed = schema.safeParse(body);
+            return parsed.success ? { ok: true, value: parsed.data } : { ok: false, kind: "unavailable", httpStatus: response.status };
+        }
+        const error = typeof body?.error === "string" ? body.error : `HTTP ${response.status}`;
+        if (response.status === 401)
+            return { ok: false, kind: "session", status: 401, error };
+        if (response.status === 403)
+            return { ok: false, kind: "forbidden", status: 403, error };
+        if (response.status >= 400 && response.status < 500)
+            return { ok: false, kind: "refused", status: response.status, error };
+        return { ok: false, kind: "unavailable", httpStatus: response.status };
+    }
+    const post = (body) => ({ method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+    return {
+        /** The agent's owner and current provider ID (`agentId`, null until created): what a consent must name. */
+        identity: (agent) => route(`/agents/${encodeURIComponent(agent)}`, appAgent),
+        /** A wallet owner's signed setup text: reserves the hosted agent and returns its setup consent. */
+        setup: (submission) => route("/setup", appSetupStored, post(submission)),
+        consents: {
+            list: (organization) => route(`/consents${organization ? `?organization=${encodeURIComponent(organization)}` : ""}`, appConsentList),
+            submit: (submission) => route("/consents", appConsentStored, post(submission)),
+            /** Permanent: the owner signs a new consent to restore access. */
+            revoke: (id) => route(`/consents/${encodeURIComponent(id)}`, appRevoked, { method: "DELETE" }),
+        },
+        /** One Organization's agent: reads and owner actions its live consents cover. */
+        agent(organization, agent) {
+            const owner = ownerClient({ base: `${root}/apps/v1/o/${encodeURIComponent(organization)}/a/${encodeURIComponent(agent)}`, fetch: authorized });
+            return {
+                call(path, ...[input, options]) {
+                    return owner.call(path, input, options);
+                },
+            };
+        },
+    };
+}

package/dist/contract/app-consent.d.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+/**
+ * An agent owner's consent for one app deployment to act for one Organization on one agent: `read` for the listed
+ * reads, `owner` to prepare and submit owner actions that only the owner's own wallet signature completes.
+ * The owner signs `consentMessage(...)` with NEP-413, recipient the platform host. The platform accepts only the exact
+ * canonical text, so what was signed and what is stored are the same bytes.
+ */
+export declare const APP_CONSENT_TYPE = "multiagency.app-consent";
+export declare const AppScope: z.ZodEnum<{
+    owner: "owner";
+    payout: "payout";
+    read: "read";
+}>;
+export type AppScope = z.infer<typeof AppScope>;
+/** Stands for an agent its server reports not created yet; only the platform's setup consent carries it, never a signed text. */
+export declare const UNBORN_AGENT = "unborn";
+export declare const appConsent: z.ZodObject<{
+    type: z.ZodLiteral<"multiagency.app-consent">;
+    version: z.ZodLiteral<1>;
+    host: z.ZodString;
+    deployment: z.ZodString;
+    organization: z.ZodString;
+    owner: z.ZodString;
+    agent: z.ZodString;
+    agentId: z.ZodString;
+    scopes: z.ZodArray<z.ZodEnum<{
+        owner: "owner";
+        payout: "payout";
+        read: "read";
+    }>>;
+    expiresAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type AppConsent = z.output<typeof appConsent>;
+/** The canonical text to sign: fixed key order, sorted scopes, no whitespace. */
+export declare function consentMessage(consent: Omit<AppConsent, "type" | "version">): string;
+/** The consent a signed text states, or null unless the text is exactly its canonical form. */
+export declare function parseConsentMessage(message: string): AppConsent | null;
+/** What the app submits after the owner signs: the text, the NEP-413 nonce (32 bytes, base64) and the signature. */
+export declare const appConsentSubmission: z.ZodObject<{
+    message: z.ZodString;
+    nonce: z.ZodString;
+    publicKey: z.ZodString;
+    signature: z.ZodString;
+}, z.core.$strict>;
+/**
+ * An agent owner's request, signed with NEP-413 like a consent, that the platform set up a hosted agent for this owner
+ * and area and let the app prepare its creation. It lasts at most an hour: it authorizes a setup, not ongoing
+ * access. Once the agent exists, the app asks for a consent naming its provider ID.
+ */
+export declare const APP_SETUP_TYPE = "multiagency.app-setup";
+export declare const appSetup: z.ZodObject<{
+    type: z.ZodLiteral<"multiagency.app-setup">;
+    version: z.ZodLiteral<1>;
+    host: z.ZodString;
+    deployment: z.ZodString;
+    organization: z.ZodString;
+    owner: z.ZodString;
+    area: z.ZodEnum<{
+        payables: "payables";
+        treasury: "treasury";
+    }>;
+    expiresAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type AppSetup = z.output<typeof appSetup>;
+/** The canonical setup text to sign: fixed key order, no whitespace. */
+export declare function setupMessage(setup: Omit<AppSetup, "type" | "version">): string;
+/** The setup a signed text states, or null unless the text is exactly its canonical form. */
+export declare function parseSetupMessage(message: string): AppSetup | null;

package/dist/contract/app-consent.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+/**
+ * An agent owner's consent for one app deployment to act for one Organization on one agent: `read` for the listed
+ * reads, `owner` to prepare and submit owner actions that only the owner's own wallet signature completes.
+ * The owner signs `consentMessage(...)` with NEP-413, recipient the platform host. The platform accepts only the exact
+ * canonical text, so what was signed and what is stored are the same bytes.
+ */
+export const APP_CONSENT_TYPE = "multiagency.app-consent";
+export const AppScope = z.enum(["owner", "payout", "read"]);
+const name = z.string().regex(/^[a-z0-9-]{1,32}$/);
+/** Stands for an agent its server reports not created yet; only the platform's setup consent carries it, never a signed text. */
+export const UNBORN_AGENT = "unborn";
+const account = z.string().min(2).max(64).regex(/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/);
+export const appConsent = z.strictObject({
+    type: z.literal(APP_CONSENT_TYPE),
+    version: z.literal(1),
+    host: z.string().min(1).max(253).regex(/^[a-z0-9.-]+(?::\d{1,5})?$/),
+    deployment: name,
+    organization: z.string().regex(/^[A-Za-z0-9_-]{1,128}$/),
+    owner: account,
+    agent: name,
+    /** The agent's provider ID when the owner signs: a replacement agent under the same name isn't covered. */
+    agentId: z.string().min(1).max(128).refine(id => id !== UNBORN_AGENT, "Not an agent ID"),
+    scopes: z.array(AppScope).min(1).refine(values => new Set(values).size === values.length, "Scopes must be distinct"),
+    expiresAt: z.iso.datetime(),
+});
+/** The canonical text to sign: fixed key order, sorted scopes, no whitespace. */
+export function consentMessage(consent) {
+    const value = appConsent.parse({ type: APP_CONSENT_TYPE, version: 1, ...consent });
+    return JSON.stringify({ type: value.type, version: value.version, host: value.host, deployment: value.deployment,
+        organization: value.organization, owner: value.owner, agent: value.agent, agentId: value.agentId, scopes: [...value.scopes].sort(), expiresAt: value.expiresAt });
+}
+/** The consent a signed text states, or null unless the text is exactly its canonical form. */
+export function parseConsentMessage(message) {
+    let value;
+    try {
+        value = JSON.parse(message);
+    }
+    catch {
+        return null;
+    }
+    const parsed = appConsent.safeParse(value);
+    if (!parsed.success)
+        return null;
+    const { type: _type, version: _version, ...fields } = parsed.data;
+    return consentMessage(fields) === message ? parsed.data : null;
+}
+/** What the app submits after the owner signs: the text, the NEP-413 nonce (32 bytes, base64) and the signature. */
+export const appConsentSubmission = z.strictObject({
+    message: z.string().min(1).max(2_048),
+    nonce: z.string().min(1).max(64),
+    publicKey: z.string().regex(/^ed25519:[1-9A-HJ-NP-Za-km-z]{32,64}$/),
+    signature: z.string().min(1).max(200),
+});
+/**
+ * An agent owner's request, signed with NEP-413 like a consent, that the platform set up a hosted agent for this owner
+ * and area and let the app prepare its creation. It lasts at most an hour: it authorizes a setup, not ongoing
+ * access. Once the agent exists, the app asks for a consent naming its provider ID.
+ */
+export const APP_SETUP_TYPE = "multiagency.app-setup";
+export const appSetup = z.strictObject({
+    type: z.literal(APP_SETUP_TYPE),
+    version: z.literal(1),
+    host: appConsent.shape.host,
+    deployment: name,
+    organization: appConsent.shape.organization,
+    owner: account,
+    area: z.enum(["treasury", "payables"]),
+    expiresAt: z.iso.datetime(),
+});
+/** The canonical setup text to sign: fixed key order, no whitespace. */
+export function setupMessage(setup) {
+    const value = appSetup.parse({ type: APP_SETUP_TYPE, version: 1, ...setup });
+    return JSON.stringify({ type: value.type, version: value.version, host: value.host, deployment: value.deployment,
+        organization: value.organization, owner: value.owner, area: value.area, expiresAt: value.expiresAt });
+}
+/** The setup a signed text states, or null unless the text is exactly its canonical form. */
+export function parseSetupMessage(message) {
+    let value;
+    try {
+        value = JSON.parse(message);
+    }
+    catch {
+        return null;
+    }
+    const parsed = appSetup.safeParse(value);
+    if (!parsed.success)
+        return null;
+    const { type: _type, version: _version, ...fields } = parsed.data;
+    return setupMessage(fields) === message ? parsed.data : null;
+}

package/dist/contract/assets.d.ts

@@ -0,0 +1,6 @@
+/** Platform asset ids. Single source: the server's policy (src/policy.ts) re-exports these. */
+export declare const ASSETS: {
+    readonly wNEAR: "nep141:wrap.near";
+    readonly USDC: "nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1";
+    readonly ETH: "nep141:eth.omft.near";
+};

package/dist/contract/assets.js

@@ -0,0 +1,6 @@
+/** Platform asset ids. Single source: the server's policy (src/policy.ts) re-exports these. */
+export const ASSETS = {
+    wNEAR: "nep141:wrap.near",
+    USDC: "nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1",
+    ETH: "nep141:eth.omft.near",
+};