@aithos/sdk 0.1.0-alpha.4 → 0.1.0-alpha.40

package/dist/src/key-store.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Stored owner identity material. Treat as opaque from the consumer's
+ * point of view — its internal shape may evolve between SDK versions
+ * (e.g. when we migrate to `CryptoKey` references). Custom KeyStore
+ * implementations should round-trip the value as-is rather than
+ * peeking inside.
+ *
+ * @public
+ */
+export interface StoredOwnerKeys {
+    /** Schema version. Today: `"0.1.0-hex"`. */
+    readonly version: "0.1.0-hex";
+    readonly did: string;
+    readonly handle: string;
+    readonly displayName: string;
+    /** Hex-encoded 32-byte Ed25519 seeds — one per sphere. */
+    readonly seedsHex: {
+        readonly root: string;
+        readonly public: string;
+        readonly circle: string;
+        readonly self: string;
+    };
+    /** ISO-8601 timestamp of the original save. Informational. */
+    readonly savedAt: string;
+}
+/**
+ * Stored delegate session material. Opaque from the consumer's
+ * point of view; see {@link StoredOwnerKeys}.
+ *
+ * @public
+ */
+export interface StoredDelegateKeys {
+    readonly version: "0.1.0-hex";
+    /** DID of the subject whose ethos this mandate authorizes. */
+    readonly subjectDid: string;
+    /** Mandate id — used as the storage key. */
+    readonly mandateId: string;
+    /** Full §4.2 SignedMandate, stored as opaque JSON. */
+    readonly mandate: Record<string, unknown>;
+    /** Grantee URN, e.g. `urn:aithos:agent:bob1`. */
+    readonly granteeId: string;
+    /** Multibase-encoded Ed25519 grantee pubkey, matches `mandate.grantee.pubkey`. */
+    readonly granteePubkeyMultibase: string;
+    /** Hex-encoded 32-byte delegate Ed25519 seed. */
+    readonly delegateSeedHex: string;
+    readonly importedAt: string;
+}
+/**
+ * Persistence backend for owner identity material and delegate
+ * bundles. Methods are async because an IndexedDB-backed
+ * implementation is the default and IDB's API is async — sync stores
+ * are still trivial to write (`memoryKeyStore`) by returning
+ * pre-resolved promises.
+ *
+ * Implementations should never throw on missing records: a fresh
+ * device returns `null` from `loadOwner` and `[]` from
+ * `listDelegates`. They should only throw on hard I/O failures
+ * (quota exceeded, schema corruption). The SDK treats throws as
+ * "store unavailable, fall through to re-auth".
+ *
+ * @public
+ */
+export interface AithosKeyStore {
+    loadOwner(): Promise<StoredOwnerKeys | null>;
+    saveOwner(owner: StoredOwnerKeys): Promise<void>;
+    clearOwner(): Promise<void>;
+    listDelegates(): Promise<readonly StoredDelegateKeys[]>;
+    loadDelegate(mandateId: string): Promise<StoredDelegateKeys | null>;
+    saveDelegate(d: StoredDelegateKeys): Promise<void>;
+    removeDelegate(mandateId: string): Promise<void>;
+    clearAllDelegates(): Promise<void>;
+}
+/**
+ * In-memory key store. Loses everything on page reload — useful for
+ * tests, SSR, ephemeral CLI tools, and any workflow where you want a
+ * deliberately short-lived session.
+ *
+ * @public
+ */
+export declare function memoryKeyStore(): AithosKeyStore;
+/**
+ * Default IndexedDB database name used by {@link indexedDbKeyStore}.
+ * Apps that want to coexist with other Aithos-aware libs (or scope
+ * sessions per-tenant) can pass a custom `dbName`.
+ */
+export declare const DEFAULT_KEYSTORE_DB_NAME = "aithos-sdk-keys";
+interface IndexedDbKeyStoreOptions {
+    /** Database name. Defaults to {@link DEFAULT_KEYSTORE_DB_NAME}. */
+    readonly dbName?: string;
+    /**
+     * Inject a non-default IDBFactory — used by tests. Apps should not
+     * pass this; the global `indexedDB` is the right choice everywhere
+     * else.
+     *
+     * @internal
+     */
+    readonly factory?: IDBFactory;
+}
+/**
+ * IndexedDB-backed key store. Default in browser environments —
+ * persists across reloads and browser restarts, scoped to the
+ * page's origin.
+ *
+ * Storage shape today:
+ *
+ *   - object store `owner`     — single record at key `"self"`,
+ *                                shape {@link StoredOwnerKeys}
+ *   - object store `delegates` — keyPath `mandateId`, shape
+ *                                {@link StoredDelegateKeys}
+ *
+ * Both stores live in DB `aithos-sdk-keys` (configurable via
+ * `dbName`) at version 1. Future versions will trigger an upgrade
+ * transaction that migrates records into the new shape.
+ *
+ * @public
+ */
+export declare function indexedDbKeyStore(opts?: IndexedDbKeyStoreOptions): AithosKeyStore;
+/**
+ * Pick a sensible default: {@link indexedDbKeyStore} when an IDBFactory
+ * is reachable (browser environments), {@link memoryKeyStore} otherwise
+ * (Node, edge runtimes — apps running there should pass their own
+ * keystore explicitly).
+ *
+ * @public
+ */
+export declare function defaultKeyStore(): AithosKeyStore;
+export {};
+//# sourceMappingURL=key-store.d.ts.map

package/dist/src/key-store.js

@@ -0,0 +1,244 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/* -------------------------------------------------------------------------- */
+/*  In-memory implementation                                                  */
+/* -------------------------------------------------------------------------- */
+/**
+ * In-memory key store. Loses everything on page reload — useful for
+ * tests, SSR, ephemeral CLI tools, and any workflow where you want a
+ * deliberately short-lived session.
+ *
+ * @public
+ */
+export function memoryKeyStore() {
+    let owner = null;
+    const delegates = new Map();
+    return {
+        async loadOwner() {
+            return owner;
+        },
+        async saveOwner(o) {
+            owner = o;
+        },
+        async clearOwner() {
+            owner = null;
+        },
+        async listDelegates() {
+            return [...delegates.values()];
+        },
+        async loadDelegate(mandateId) {
+            return delegates.get(mandateId) ?? null;
+        },
+        async saveDelegate(d) {
+            delegates.set(d.mandateId, d);
+        },
+        async removeDelegate(mandateId) {
+            delegates.delete(mandateId);
+        },
+        async clearAllDelegates() {
+            delegates.clear();
+        },
+    };
+}
+/* -------------------------------------------------------------------------- */
+/*  IndexedDB implementation                                                  */
+/* -------------------------------------------------------------------------- */
+/**
+ * Default IndexedDB database name used by {@link indexedDbKeyStore}.
+ * Apps that want to coexist with other Aithos-aware libs (or scope
+ * sessions per-tenant) can pass a custom `dbName`.
+ */
+export const DEFAULT_KEYSTORE_DB_NAME = "aithos-sdk-keys";
+const STORE_OWNER = "owner";
+const STORE_DELEGATES = "delegates";
+/** The single owner record always lives at this key — the store has no keyPath. */
+const OWNER_KEY = "self";
+/**
+ * IndexedDB-backed key store. Default in browser environments —
+ * persists across reloads and browser restarts, scoped to the
+ * page's origin.
+ *
+ * Storage shape today:
+ *
+ *   - object store `owner`     — single record at key `"self"`,
+ *                                shape {@link StoredOwnerKeys}
+ *   - object store `delegates` — keyPath `mandateId`, shape
+ *                                {@link StoredDelegateKeys}
+ *
+ * Both stores live in DB `aithos-sdk-keys` (configurable via
+ * `dbName`) at version 1. Future versions will trigger an upgrade
+ * transaction that migrates records into the new shape.
+ *
+ * @public
+ */
+export function indexedDbKeyStore(opts = {}) {
+    const dbName = opts.dbName ?? DEFAULT_KEYSTORE_DB_NAME;
+    const factory = opts.factory ??
+        (typeof indexedDB !== "undefined" ? indexedDB : undefined);
+    if (!factory) {
+        throw new Error("indexedDbKeyStore: no IDBFactory available — pass `factory` for non-browser environments or use memoryKeyStore() instead.");
+    }
+    const open = () => new Promise((resolve, reject) => {
+        const req = factory.open(dbName, 1);
+        req.onupgradeneeded = () => {
+            const db = req.result;
+            if (!db.objectStoreNames.contains(STORE_OWNER)) {
+                db.createObjectStore(STORE_OWNER);
+            }
+            if (!db.objectStoreNames.contains(STORE_DELEGATES)) {
+                db.createObjectStore(STORE_DELEGATES, { keyPath: "mandateId" });
+            }
+        };
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error ?? new Error("indexedDB.open failed"));
+    });
+    const tx = async (stores, mode, run) => {
+        const db = await open();
+        try {
+            const t = db.transaction([...stores], mode);
+            const result = await Promise.resolve(run(t));
+            await new Promise((resolve, reject) => {
+                t.oncomplete = () => resolve();
+                t.onerror = () => reject(t.error ?? new Error("transaction failed"));
+                t.onabort = () => reject(t.error ?? new Error("transaction aborted"));
+            });
+            return result;
+        }
+        finally {
+            db.close();
+        }
+    };
+    const reqAsPromise = (req) => new Promise((resolve, reject) => {
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error ?? new Error("IDBRequest failed"));
+    });
+    return {
+        async loadOwner() {
+            return tx([STORE_OWNER], "readonly", async (t) => {
+                const v = await reqAsPromise(t.objectStore(STORE_OWNER).get(OWNER_KEY));
+                return validOwnerOrNull(v);
+            });
+        },
+        async saveOwner(owner) {
+            await tx([STORE_OWNER], "readwrite", (t) => {
+                t.objectStore(STORE_OWNER).put(owner, OWNER_KEY);
+            });
+        },
+        async clearOwner() {
+            await tx([STORE_OWNER], "readwrite", (t) => {
+                t.objectStore(STORE_OWNER).delete(OWNER_KEY);
+            });
+        },
+        async listDelegates() {
+            return tx([STORE_DELEGATES], "readonly", async (t) => {
+                const all = await reqAsPromise(t.objectStore(STORE_DELEGATES).getAll());
+                return all
+                    .map(validDelegateOrNull)
+                    .filter((d) => d !== null);
+            });
+        },
+        async loadDelegate(mandateId) {
+            return tx([STORE_DELEGATES], "readonly", async (t) => {
+                const v = await reqAsPromise(t.objectStore(STORE_DELEGATES).get(mandateId));
+                return validDelegateOrNull(v);
+            });
+        },
+        async saveDelegate(d) {
+            await tx([STORE_DELEGATES], "readwrite", (t) => {
+                t.objectStore(STORE_DELEGATES).put(d);
+            });
+        },
+        async removeDelegate(mandateId) {
+            await tx([STORE_DELEGATES], "readwrite", (t) => {
+                t.objectStore(STORE_DELEGATES).delete(mandateId);
+            });
+        },
+        async clearAllDelegates() {
+            await tx([STORE_DELEGATES], "readwrite", (t) => {
+                t.objectStore(STORE_DELEGATES).clear();
+            });
+        },
+    };
+}
+/* -------------------------------------------------------------------------- */
+/*  Default picker                                                            */
+/* -------------------------------------------------------------------------- */
+/**
+ * Pick a sensible default: {@link indexedDbKeyStore} when an IDBFactory
+ * is reachable (browser environments), {@link memoryKeyStore} otherwise
+ * (Node, edge runtimes — apps running there should pass their own
+ * keystore explicitly).
+ *
+ * @public
+ */
+export function defaultKeyStore() {
+    if (typeof indexedDB !== "undefined") {
+        try {
+            return indexedDbKeyStore();
+        }
+        catch {
+            return memoryKeyStore();
+        }
+    }
+    return memoryKeyStore();
+}
+/* -------------------------------------------------------------------------- */
+/*  Runtime validators                                                        */
+/*                                                                             */
+/*  Storage values come from JSON-shaped records that may have been written   */
+/*  by an older SDK version, by a corrupted process, or by an attacker with   */
+/*  IDB write access. The SDK trusts only records that round-trip through     */
+/*  these validators; anything else is treated as "no record" so the resume   */
+/*  path falls through to re-auth.                                            */
+/* -------------------------------------------------------------------------- */
+function validOwnerOrNull(v) {
+    if (typeof v !== "object" || v === null)
+        return null;
+    const o = v;
+    if (o["version"] !== "0.1.0-hex")
+        return null;
+    if (typeof o["did"] !== "string")
+        return null;
+    if (typeof o["handle"] !== "string")
+        return null;
+    if (typeof o["displayName"] !== "string")
+        return null;
+    const seeds = o["seedsHex"];
+    if (typeof seeds !== "object" || seeds === null)
+        return null;
+    const s = seeds;
+    for (const k of ["root", "public", "circle", "self"]) {
+        if (typeof s[k] !== "string")
+            return null;
+        if (s[k].length !== 64)
+            return null;
+    }
+    if (typeof o["savedAt"] !== "string")
+        return null;
+    return o;
+}
+function validDelegateOrNull(v) {
+    if (typeof v !== "object" || v === null)
+        return null;
+    const o = v;
+    if (o["version"] !== "0.1.0-hex")
+        return null;
+    if (typeof o["subjectDid"] !== "string")
+        return null;
+    if (typeof o["mandateId"] !== "string")
+        return null;
+    if (typeof o["granteeId"] !== "string")
+        return null;
+    if (typeof o["granteePubkeyMultibase"] !== "string")
+        return null;
+    if (typeof o["delegateSeedHex"] !== "string")
+        return null;
+    if (o["delegateSeedHex"].length !== 64)
+        return null;
+    if (typeof o["mandate"] !== "object" || o["mandate"] === null)
+        return null;
+    if (typeof o["importedAt"] !== "string")
+        return null;
+    return o;
+}
+//# sourceMappingURL=key-store.js.map

package/dist/src/mandates.d.ts

@@ -1,2 +1,164 @@
-export { mintDelegateBundle, signAndPublishMandate, MintError, type MintArgs, type MintResult, type SignAndPublishMandateArgs, DEFAULT_READ_SCOPES, TTL_PRESETS, } from "@aithos/protocol-client";
+import type { AithosAuth } from "./auth.js";
+import type { AithosSdkEndpoints } from "./endpoints.js";
+/** Capability scope the SDK accepts. Server-side ultimately decides.
+ *
+ * Note: `compute.invoke` is intentionally NOT in this union. The token-
+ * spending capability is opt-in via the dedicated {@link CreateMandateInput.compute}
+ * namespace — see {@link MandatesNamespace.create}. Passing `compute.invoke`
+ * directly in `scopes` is rejected at runtime; the compiler can't enforce
+ * it (callers who up-cast to string[] would slip through), so the runtime
+ * check is the real gate. */
+export type Scope = "ethos.read.public" | "ethos.read.circle" | "ethos.read.self" | "ethos.write.public" | "ethos.write.circle" | "ethos.write.self";
+/**
+ * The opt-in scope that authorizes a delegate to spend the subject's
+ * compute credits via the Aithos compute proxy. Mirror of
+ * `COMPUTE_INVOKE_SCOPE` in `@aithos/protocol-core` v0.4.0.
+ *
+ * The SDK's `mandates.create()` injects this scope automatically when
+ * the caller passes a `compute` namespace, and refuses to mint a
+ * mandate where the caller put it directly into `scopes` — this is
+ * what makes "compute is a separate, conscious decision" hold at the
+ * API surface.
+ */
+export declare const COMPUTE_INVOKE_SCOPE: "compute.invoke";
+/**
+ * Which sphere of the owner signs the mandate. Bounds the upper-most
+ * scope set the mandate can carry.
+ */
+export type ActorSphere = "public" | "circle" | "self";
+/**
+ * Compute-spending capability — opt-in only, never implied by ethos
+ * scopes.
+ *
+ * When `compute` is set on {@link CreateMandateInput}, the SDK:
+ *   1. Adds the `compute.invoke` scope to the minted mandate.
+ *   2. Maps the caller's caps onto `constraints.compute` in the
+ *      protocol's snake_case shape (= what the verifier reads).
+ *   3. Forbids the caller from passing `compute.invoke` in `scopes`
+ *      directly — that would let an app slip the scope past a
+ *      consent UI that only reviews `compute`.
+ *
+ * At least one of `dailyCapMicrocredits` or `totalCapMicrocredits` MUST
+ * be set: an unbounded compute mandate is the kind of bearer-token
+ * footgun this whole namespace exists to prevent. Validation happens
+ * at the SDK boundary (here) AND at the protocol layer (the
+ * server-side verifier rejects capless 0.4.0 mandates), so a bug in
+ * either tier still fails closed.
+ *
+ * `maxCreditsPerCall` is a per-invocation safety net for runaway
+ * single requests. `allowedModels`, when set, restricts which Bedrock
+ * model ids the delegate may target (the proxy's own allowlist still
+ * applies on top).
+ */
+export interface CreateMandateComputeInput {
+    /** Hard cap on credits debited per UTC day under this mandate. */
+    readonly dailyCapMicrocredits?: number;
+    /** Hard cap on credits debited over the whole mandate lifetime. */
+    readonly totalCapMicrocredits?: number;
+    /** Hard cap on credits debited by any single invocation. */
+    readonly maxCreditsPerCall?: number;
+    /** Allowlist of Bedrock model ids the delegate may invoke. */
+    readonly allowedModels?: readonly string[];
+}
+export interface CreateMandateInput {
+    /** Grantee URN — usually `urn:aithos:agent:<extension-id>` or similar. */
+    readonly granteeId: string;
+    /** Optional human-readable label for the grantee. */
+    readonly granteeLabel?: string;
+    /**
+     * Sphere of the owner that issues the mandate. Defaults to the
+     * highest-numbered sphere covered by `scopes` (most permissive
+     * common ancestor): `"self"` if any scope ends in `.self`, else
+     * `"circle"` if any ends in `.circle`, else `"public"`.
+     */
+    readonly actorSphere?: ActorSphere;
+    /** Capability set granted by the mandate. */
+    readonly scopes: readonly Scope[];
+    /** Lifetime in seconds. */
+    readonly ttlSeconds: number;
+    /**
+     * Opt-in compute (token-spending) capability — adds the
+     * `compute.invoke` scope and a bounded `constraints.compute` budget
+     * to the mandate. See {@link CreateMandateComputeInput}.
+     *
+     * NEVER add `compute.invoke` to `scopes` directly — the SDK rejects
+     * that path so the caller has to pass through this typed namespace,
+     * which is what a consent UI can review.
+     */
+    readonly compute?: CreateMandateComputeInput;
+    /**
+     * When the mandate becomes valid. Optional — when omitted, the
+     * underlying mint helper signs with `not_before = now - 30s` (see
+     * `MANDATE_NOTBEFORE_OFFSET_SECONDS_DEFAULT` in
+     * `@aithos/protocol-client`) so a server whose clock runs slightly
+     * behind the client doesn't reject the freshly-minted mandate as
+     * `not yet valid`.
+     *
+     * Pass an explicit `Date` only for advanced flows (delayed-activation
+     * mandates, deterministic tests).
+     */
+    readonly notBefore?: Date;
+}
+export interface MintedMandate {
+    /** Unique mandate id (matches `mandate.id` inside the bundle). */
+    readonly mandateId: string;
+    /** Subject DID — the owner who issued it. */
+    readonly subjectDid: string;
+    /** Grantee URN. */
+    readonly granteeId: string;
+    readonly scopes: readonly Scope[];
+    /** ISO-8601 (UTC) — `null` if the mandate has no `not_after`. */
+    readonly expiresAt: string | null;
+    /** Shareable `.aithos-delegate.json` Blob. Hand this to the grantee. */
+    readonly bundle: Blob;
+    /** Suggested filename for the bundle. */
+    readonly filename: string;
+}
+export interface OwnedMandate {
+    readonly mandateId: string;
+    readonly issuerDid: string;
+    readonly actorDid: string;
+    readonly scopes: readonly Scope[];
+    readonly notBefore: number | null;
+    readonly notAfter: number | null;
+    readonly createdAt: number;
+}
+export interface MandatesNamespaceDeps {
+    readonly auth: AithosAuth;
+    readonly endpoints: AithosSdkEndpoints;
+    readonly fetch: typeof fetch;
+}
+export declare class MandatesNamespace {
+    #private;
+    constructor(deps: MandatesNamespaceDeps);
+    /**
+     * Mint, sign, publish, and package a fresh delegate bundle. The
+     * grantee's keypair is generated inside this call and never
+     * persisted on the owner's machine — the seed flows out via the
+     * returned Blob and only via that Blob.
+     */
+    create(input: CreateMandateInput): Promise<MintedMandate>;
+    /**
+     * List mandates issued by the signed-in owner. Pages through
+     * `aithos.list_mandates` until exhausted (or until 5 pages have
+     * been crawled — an owner with more than 1000 active mandates is
+     * out of scope today).
+     */
+    list(): Promise<readonly OwnedMandate[]>;
+    /**
+     * Publish a §4.2 revocation for `mandateId`. The mandate stops
+     * authorizing future actions (artifacts dated before `revoked_at`
+     * remain valid — revocation is not retroactive).
+     *
+     * Server-side: handled by `aithos.publish_revocation`. The envelope
+     * is signed by the owner's `#public` sphere — the spec also accepts
+     * `#root`, but `#public` is what the existing app does.
+     *
+     * Throws {@link AithosSDKError} on backend errors. Note that
+     * server-side support is in-flight; this method may surface a
+     * `mandates_-32601` (method not found) until the auth platform
+     * lands the corresponding write handler.
+     */
+    revoke(mandateId: string): Promise<void>;
+}
 //# sourceMappingURL=mandates.d.ts.map