@mida-context/sdk 0.1.0

package/dist/types/protocol/owner-link.d.ts

@@ -0,0 +1,146 @@
+import type { Address, Hex } from "./types.js";
+/**
+ * The wire contract between the terminal (`mida init --passkey`, `approve`, `revoke`) and the
+ * owner page at https://app.midacontext.xyz. `apps/owner-page/PROTOCOL.md` is the spec; this
+ * file is the ONE implementation both sides share — the page and the terminal must never drift
+ * on request shape, hashing or the pairing code.
+ *
+ * In:  `https://<origin>/<flow>#v=1&req=<base64url JSON>&port=<n>&nonce=<hex16>`
+ * Out: `http://127.0.0.1:<port>/mida-return#nonce=<nonce>&result=<base64url JSON>`
+ *
+ * Two rules do the security work:
+ *  - Everything identity-relevant lives inside `req`, so `requestHash = sha256(reqBytes)` covers
+ *    all of it — and the same bytes feed the pairing code.
+ *  - The result carries no secret material — `buildOwnerResult` runs the sanitiser and refuses
+ *    to serialize a 32-byte value under a key whose name contains prf, seed, secret, private, key.
+ *
+ * This module is bundled into the browser page — no node imports, no Buffer, no process.
+ */
+export type OwnerLinkFlow = "signup" | "approve" | "revoke";
+export declare class OwnerLinkError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+export interface OwnerLinkProject {
+    id: string;
+    label: string;
+}
+/**
+ * The decoded `req` envelope. Fields are flow-specific: `request`+`manifest` belong to approve,
+ * `agentId`+`readers` to revoke, `entries` to the project-list signature the page returns. The
+ * parser checks the envelope's shape and field types; the flows verify the contents (agent
+ * signature, manifest hash, chain state) before any passkey prompt.
+ */
+export interface OwnerLinkRequest {
+    chainId: number;
+    /** Expected owner address — present on approve/revoke, absent on signup. */
+    owner?: Address;
+    /** The agent's signed access request (approve). Deep verification happens in the advisor. */
+    request?: Record<string, unknown>;
+    /** The agent's signed manifest, if the terminal inlined it; else the page fetches it. */
+    manifest?: Record<string, unknown>;
+    /** The agent to revoke (revoke). */
+    agentId?: Hex;
+    /** Agent ids the terminal believes survive a revoke — re-checked on chain before re-wrapping. */
+    readers?: Hex[];
+    project?: OwnerLinkProject;
+    /** Current project-list entries the page re-signs after an approve. */
+    entries?: Record<string, unknown>[];
+    /** The new approved-projects row to append (approve): {agent, projectId, root}. */
+    entry?: {
+        agent: string;
+        projectId: string;
+        root: string;
+    };
+}
+export interface ParsedOwnerLink {
+    flow: OwnerLinkFlow;
+    /** The exact decoded req bytes — the pairing code and requestHash both derive from these. */
+    requestBytes: Uint8Array;
+    requestHash: Hex;
+    req: OwnerLinkRequest;
+    nonce: string;
+    /** Absent when the link carries no port — the page then shows the result instead of returning. */
+    port?: number;
+}
+export declare function ownerLinkBase64UrlEncode(bytes: Uint8Array): string;
+export declare function ownerLinkBase64UrlDecode(text: string): Uint8Array;
+/** Throws on the first 32-byte value found under a secret-looking key, anywhere in the tree. */
+export declare function assertNoSecretMaterial(value: unknown, path?: string): void;
+/**
+ * 256 common, distinct words — one per byte value. Chosen to be easy to say over a screen share
+ * and hard to confuse with each other; the list is the contract, so the entries and their order
+ * never change.
+ */
+export declare const PAIRING_WORDS: readonly string[];
+/**
+ * Three words and two digits from the exact request bytes. Example: "atlas sugar orbit 07".
+ * Both sides call this on the same bytes and must print the same string.
+ *
+ * FROZEN: the word list, the domain separator, and the byte-to-code mapping are the wire
+ * contract between the page and the terminal. Changing any of them orphans every in-flight
+ * request — bump the "v1" tag instead, never edit in place.
+ */
+export declare function pairingCode(requestBytes: Uint8Array): string;
+/** sha256 of the exact request bytes, as 0x-hex — what the result's `requestHash` must equal. */
+export declare function requestHash(requestBytes: Uint8Array): Hex;
+/**
+ * Parse the link fragment. `fragment` is everything after `#` in the page URL. Every check that
+ * can fail throws OwnerLinkError with a plain-words reason — a malformed link is refused before
+ * any passkey prompt, and the page shows the reason so the owner can tell a broken terminal from
+ * a forged link.
+ */
+export declare function parseOwnerLink(fragment: string, flow: OwnerLinkFlow): ParsedOwnerLink;
+/**
+ * Terminal side: build the page link for a request. The request object is validated by the same
+ * rules the page applies, then serialized once — `requestBytes` is exactly what the page decodes,
+ * so the pairing code and the result's `requestHash` can never drift apart.
+ */
+export declare function buildOwnerLink(input: {
+    origin: string;
+    flow: OwnerLinkFlow;
+    req: OwnerLinkRequest;
+    nonce: string;
+    port?: number;
+}): {
+    url: string;
+    requestBytes: Uint8Array;
+    requestHash: Hex;
+};
+/** What the page hands back to the terminal — and nothing more. See PROTOCOL.md. */
+export interface OwnerLinkResult {
+    v: 1;
+    /** "pending" is the sponsor-accepted-but-unconfirmed state — carries the operation hash, never a resend. */
+    status: "success" | "cancelled" | "failed" | "pending";
+    nonce: string;
+    requestHash: Hex;
+    owner: Address | null;
+    transactions: Hex[];
+    operations: Hex[];
+    /** The signed project-list entry (approve only). */
+    entry?: Record<string, unknown>;
+    /** The passkey's P-256 point (signup only). */
+    publicKey?: {
+        x: Hex;
+        y: Hex;
+    };
+    /** Plain-words reason when status is "failed" or "cancelled". */
+    reason?: string;
+}
+/**
+ * Build the result object the page returns. The sanitiser is the guard: any 32-byte value under
+ * a secret-looking key name — anywhere in the structure — throws before it can reach the URL.
+ */
+export declare function buildOwnerResult(result: OwnerLinkResult): OwnerLinkResult;
+/**
+ * Serialize the result and wrap it in the local return URL. The host is ALWAYS the literal
+ * 127.0.0.1 — never a name, never taken from the link — so a crafted link cannot aim the result
+ * at another machine.
+ */
+export declare function buildOwnerReturnUrl(port: number, nonce: string, result: OwnerLinkResult): string;
+/**
+ * Terminal side: decode and validate the `result=` fragment parameter. Strict about keys, types
+ * and the no-secret-material rule — a result that does not match this shape is a page bug or a
+ * forgery and is refused before the caller reads a single field.
+ */
+export declare function parseOwnerResult(encoded: string): OwnerLinkResult;

package/dist/types/protocol/typed-data.d.ts

@@ -0,0 +1,365 @@
+import type { Address, Hex } from "viem";
+import type { AccessRequest } from "./types.js";
+export type UnsignedAccessRequest = Omit<AccessRequest, "agentSignature">;
+export declare const DOMAIN_NAMES: {
+    readonly capabilityRegistry: "Mida Capability Registry";
+    readonly accessRequest: "Mida Context";
+    readonly manifest: "Mida Agent Capability Manifest";
+    readonly httpRequest: "Mida Context API";
+};
+export declare function midaDomain(name: string, chainId: bigint, verifyingContract: Address): {
+    name: string;
+    version: string;
+    chainId: bigint;
+    verifyingContract: `0x${string}`;
+};
+export declare const ACCESS_REQUEST_TYPES: {
+    readonly MidaAccessRequestV1: readonly [{
+        readonly name: "requestId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "agentId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "purposeIdHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "callbackOriginHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "manifestHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "manifestVersion";
+        readonly type: "uint64";
+    }, {
+        readonly name: "policyVersionHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "namespaceTreeVersionHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "scopesHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "issuedAt";
+        readonly type: "uint64";
+    }, {
+        readonly name: "requestExpiresAt";
+        readonly type: "uint64";
+    }, {
+        readonly name: "capabilityExpiresAt";
+        readonly type: "uint64";
+    }];
+};
+export declare const MANIFEST_BINDING_TYPES: {
+    readonly ManifestBinding: readonly [{
+        readonly name: "bodyHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "agentId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "manifestVersion";
+        readonly type: "uint64";
+    }];
+};
+export declare const HTTP_REQUEST_TYPES: {
+    readonly MidaHttpRequestV1: readonly [{
+        readonly name: "signer";
+        readonly type: "address";
+    }, {
+        readonly name: "methodHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "targetHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "bodyHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "timestamp";
+        readonly type: "uint64";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }];
+};
+export declare const AGENT_REGISTRATION_TYPES: {
+    readonly MidaAgentRegistrationV1: readonly [{
+        readonly name: "agentId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "operator";
+        readonly type: "address";
+    }, {
+        readonly name: "signer";
+        readonly type: "address";
+    }, {
+        readonly name: "encryptionPublicKey";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "encryptionKeyVersion";
+        readonly type: "uint32";
+    }, {
+        readonly name: "callbackOriginHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "capabilityManifestHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "capabilityManifestVersion";
+        readonly type: "uint64";
+    }];
+};
+export declare const SIGNER_ROTATION_TYPES: {
+    readonly MidaSignerRotationV1: readonly [{
+        readonly name: "agentId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "newSigner";
+        readonly type: "address";
+    }, {
+        readonly name: "rotationNonce";
+        readonly type: "uint64";
+    }];
+};
+export declare function accessRequestTypedData(request: UnsignedAccessRequest): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: bigint;
+        verifyingContract: `0x${string}`;
+    };
+    types: {
+        readonly MidaAccessRequestV1: readonly [{
+            readonly name: "requestId";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "nonce";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "agentId";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "purposeIdHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "callbackOriginHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "manifestHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "manifestVersion";
+            readonly type: "uint64";
+        }, {
+            readonly name: "policyVersionHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "namespaceTreeVersionHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "scopesHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "issuedAt";
+            readonly type: "uint64";
+        }, {
+            readonly name: "requestExpiresAt";
+            readonly type: "uint64";
+        }, {
+            readonly name: "capabilityExpiresAt";
+            readonly type: "uint64";
+        }];
+    };
+    primaryType: "MidaAccessRequestV1";
+    message: {
+        requestId: `0x${string}`;
+        nonce: `0x${string}`;
+        agentId: `0x${string}`;
+        purposeIdHash: `0x${string}`;
+        callbackOriginHash: `0x${string}`;
+        manifestHash: `0x${string}`;
+        manifestVersion: bigint;
+        policyVersionHash: `0x${string}`;
+        namespaceTreeVersionHash: `0x${string}`;
+        scopesHash: `0x${string}`;
+        issuedAt: bigint;
+        requestExpiresAt: bigint;
+        capabilityExpiresAt: bigint;
+    };
+};
+export declare const accessRequestHash: (request: UnsignedAccessRequest) => Hex;
+export declare function manifestBindingTypedData(input: {
+    chainId: bigint;
+    capabilityRegistry: Address;
+    bodyHash: Hex;
+    agentId: Hex;
+    manifestVersion: bigint;
+}): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: bigint;
+        verifyingContract: `0x${string}`;
+    };
+    types: {
+        readonly ManifestBinding: readonly [{
+            readonly name: "bodyHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "agentId";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "manifestVersion";
+            readonly type: "uint64";
+        }];
+    };
+    primaryType: "ManifestBinding";
+    message: {
+        bodyHash: `0x${string}`;
+        agentId: `0x${string}`;
+        manifestVersion: bigint;
+    };
+};
+export declare function canonicalTarget(pathname: string, query?: Record<string, string>): string;
+export declare function httpRequestTypedData(input: {
+    chainId: bigint;
+    capabilityRegistry: Address;
+    signer: Address;
+    method: string;
+    target: string;
+    body: Uint8Array;
+    timestamp: bigint;
+    nonce: Hex;
+}): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: bigint;
+        verifyingContract: `0x${string}`;
+    };
+    types: {
+        readonly MidaHttpRequestV1: readonly [{
+            readonly name: "signer";
+            readonly type: "address";
+        }, {
+            readonly name: "methodHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "targetHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "bodyHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "timestamp";
+            readonly type: "uint64";
+        }, {
+            readonly name: "nonce";
+            readonly type: "bytes32";
+        }];
+    };
+    primaryType: "MidaHttpRequestV1";
+    message: {
+        signer: `0x${string}`;
+        methodHash: `0x${string}`;
+        targetHash: `0x${string}`;
+        bodyHash: `0x${string}`;
+        timestamp: bigint;
+        nonce: `0x${string}`;
+    };
+};
+export declare function agentRegistrationTypedData(input: {
+    chainId: bigint;
+    capabilityRegistry: Address;
+    agentId: Hex;
+    operator: Address;
+    signer: Address;
+    encryptionPublicKey: Hex;
+    encryptionKeyVersion: number;
+    callbackOriginHash: Hex;
+    capabilityManifestHash: Hex;
+    capabilityManifestVersion: bigint;
+}): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: bigint;
+        verifyingContract: `0x${string}`;
+    };
+    types: {
+        readonly MidaAgentRegistrationV1: readonly [{
+            readonly name: "agentId";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "operator";
+            readonly type: "address";
+        }, {
+            readonly name: "signer";
+            readonly type: "address";
+        }, {
+            readonly name: "encryptionPublicKey";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "encryptionKeyVersion";
+            readonly type: "uint32";
+        }, {
+            readonly name: "callbackOriginHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "capabilityManifestHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "capabilityManifestVersion";
+            readonly type: "uint64";
+        }];
+    };
+    primaryType: "MidaAgentRegistrationV1";
+    message: {
+        agentId: `0x${string}`;
+        operator: `0x${string}`;
+        signer: `0x${string}`;
+        encryptionPublicKey: `0x${string}`;
+        encryptionKeyVersion: number;
+        callbackOriginHash: `0x${string}`;
+        capabilityManifestHash: `0x${string}`;
+        capabilityManifestVersion: bigint;
+    };
+};
+export declare function signerRotationTypedData(input: {
+    chainId: bigint;
+    capabilityRegistry: Address;
+    agentId: Hex;
+    newSigner: Address;
+    rotationNonce: bigint;
+}): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: bigint;
+        verifyingContract: `0x${string}`;
+    };
+    types: {
+        readonly MidaSignerRotationV1: readonly [{
+            readonly name: "agentId";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "newSigner";
+            readonly type: "address";
+        }, {
+            readonly name: "rotationNonce";
+            readonly type: "uint64";
+        }];
+    };
+    primaryType: "MidaSignerRotationV1";
+    message: {
+        agentId: `0x${string}`;
+        newSigner: `0x${string}`;
+        rotationNonce: bigint;
+    };
+};