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

package/README.md

@@ -55,15 +55,219 @@ const reply = await sdk.compute.invokeBedrock({
 console.log(reply.content);
 ```
 
+## Delegating compute to an agent — opt-in token spending
+
+To let an agent (or another user, or a third-party app) invoke Bedrock
+**in your name**, with **your credits**, you mint a mandate. Token
+spending is its own opt-in capability — passing it is a separate,
+named, validated input that a consent UI can review. It is NEVER an
+implicit side-effect of an ethos read/write scope.
+
+```ts
+// Mint a mandate that lets agent Bob read your public ethos AND
+// spend up to 5 000 microcredits/day on Haiku, capped at 100 000
+// microcredits over the whole mandate lifetime.
+const mandate = await sdk.mandates.create({
+  granteeId: "urn:agent:bob",
+  scopes: ["ethos.read.public"],
+  ttlSeconds: 86_400,
+  compute: {
+    dailyCapMicrocredits: 5_000,
+    totalCapMicrocredits: 100_000,
+    maxCreditsPerCall: 500,
+    allowedModels: ["claude-haiku-4-5"],
+  },
+});
+
+// Hand `mandate.bundle` (a `.aithos-delegate.json` Blob) to Bob.
+// He imports it, then signs his own envelopes and calls
+// sdk.compute.invokeBedrock({ mandateId: mandate.mandateId, … })
+// — every invocation debits *your* wallet, capped per the budget
+// you set.
+```
+
+Three invariants the SDK enforces synchronously, before reaching the
+network — they fail fast with a precise `AithosSDKError`:
+
+- **No smuggling.** Adding `"compute.invoke"` directly to `scopes[]`
+  throws `mandates_invalid_scopes`. The `compute` namespace is the
+  only path, so a UI reviewing `compute` can never be bypassed.
+- **No bearer compute.** A `compute` namespace without at least one
+  of `dailyCapMicrocredits` or `totalCapMicrocredits` throws
+  `mandates_invalid_compute`. Unbounded compute mandates are forbidden
+  by construction.
+- **Compute-only is fine.** `scopes: []` is allowed when `compute` is
+  set — useful for agents that only consume tokens (e.g. creative
+  assistants) without seeing any of your data.
+
+## Custodial auth — onboarding users without a recovery file
+
+Three new methods on `AithosAuth` let an app create and authenticate
+its end-users via a server-managed custody flow — the user only needs
+an email address and a password sent by mail. No recovery file, no
+Google account, no client-side cryptography to handle.
+
+The model is honest custody: Aithos KMS-wraps the user's Ed25519
+identity seeds, and unwraps them on every sign-in after password
+verification. Equivalent to how Coinbase or any hosted SaaS keeps your
+private key. Annunciated to the user in the welcome email.
+
+```ts
+import { AithosSDK } from "@aithos/sdk";
+
+// ─── Server-side: sign-up ───────────────────────────────────────────
+// MUST run on your backend. The API key is a server secret —
+// provisioned by Aithos via the operator runbook.
+const sdk = new AithosSDK({ identity });
+const result = await sdk.auth.signUpCustodial({
+  apiKey: process.env.AITHOS_API_KEY!,
+  email: "alice@example.com",
+  displayName: "Alice",
+});
+// → { userId, did, handle, email, mailSent }
+// The user receives an email with their password and a sign-in link.
+
+// ─── Browser-side: sign-in ──────────────────────────────────────────
+// User pastes the password from their mail into your sign-in form,
+// then your frontend calls this. No API key needed — the password
+// is the credential.
+const { session, passwordMustChange } = await sdk.auth.signInCustodial({
+  email: "alice@example.com",
+  password: "MyTempPass32chars",
+});
+// Local KeyStore is now hydrated with the 4 Ed25519 sphere seeds —
+// the user can publish ethos editions, mint mandates, invoke compute,
+// exactly as if they had signed in via a recovery file or Google SSO.
+if (passwordMustChange) {
+  // Optional: nudge the user to set their own password via the
+  // standard reset flow.
+}
+
+// ─── Browser-side: request password reset ───────────────────────────
+// The backend always returns silently (anti-enumeration). If the email
+// is registered AND in custodial mode AND not in cooldown AND under the
+// daily cap, a magic-link email is sent to the address.
+await sdk.auth.requestPasswordReset({ email: "alice@example.com" });
+```
+
+The reset finalization (collecting the new password from the user) is
+done on a small web page hosted by Aithos at `https://app.aithos.be/reset`
+(or your app's own `reset_base_url` if you've registered one — see the
+operator runbook). The page POSTs to `/auth/custodial/reset/finalize`
+and returns the user to your sign-in page on success.
+
+### Getting an API key
+
+API keys are provisioned out-of-band by Aithos. Contact the maintainer
+(or use the self-service console at `aithos.be/console` when it ships
+in V2). The pattern is `aithos_<env>_<32 chars b58>`. Keep it in your
+backend's secrets manager — never in browser code.
+
+### Trade-offs vs. the zk and Google SSO flows
+
+|                | zk (recovery file)         | Google SSO (KMS)     | **Custodial** |
+|----------------|----------------------------|----------------------|---------------|
+| User burden    | downloads `recovery.json`  | Google consent       | email only    |
+| Password reset | requires recovery file     | re-auth via Google   | magic-link mail |
+| Trust model    | zero-knowledge (you only)  | Aithos + Google      | Aithos only   |
+| Multi-device   | re-import recovery         | re-Google            | email + password |
+| SDK signing capability | full                | full                 | full          |
+
+Custodial is the right default for SDK-integrated apps that want
+SaaS-grade UX. zk is the right default for power users who want
+sovereign custody. SSO is the right default for users already invested
+in the Google ecosystem.
+
+## Extracting webpages without an LLM
+
+`sdk.web` is a token-priced primitive that lets your agent read a
+public webpage and get back cleaned HTML, purged CSS and a
+deterministic visual signature — all computed server-side without an
+LLM in the loop. Pricing is a flat **1 microcredit** per successful
+extraction (refunded on failure), versus ~30 mc for a comparable
+LLM-based extraction.
+
+```ts
+import { AithosSDK } from "@aithos/sdk";
+
+const sdk = new AithosSDK({ auth, appDid });
+
+const { data, creditsCharged } = await sdk.web.extract({
+  url: "https://example.com",
+});
+
+console.log(data.meta.title);             // "Example Domain"
+console.log(data.visual_signature.colors.primary); // "#0078d4"
+console.log(data.styles.css.length);      // purged + minified CSS
+```
+
+Owners can mint a mandate for delegate-only extraction:
+
+```ts
+import { WEB_EXTRACT_SCOPE } from "@aithos/sdk";
+
+await sdk.mandates.create({
+  appDid: "did:aithos:app:my-agent",
+  scopes: [WEB_EXTRACT_SCOPE],
+  // ...
+});
+```
+
+## Calling a third-party Aithos-aware backend
+
+If your app talks to its own backend (a service you built that verifies
+Aithos envelopes per spec §11.2 using
+`@aithos/protocol-core/envelope`), use `sdk.auth.signEnvelope` to sign
+the request with the same primitive that SDK namespaces use internally
+for `api.aithos.be`. No JWT, no shadow session — the user's DID in the
+envelope's `iss` field is the identity.
+
+```ts
+import { AithosSDK, type SignedEnvelope } from "@aithos/sdk";
+
+// Sign a request to your own backend with the active owner's
+// public-sphere key. Default TTL is 60 s.
+const envelope: SignedEnvelope = await sdk.auth.signEnvelope({
+  aud: "https://api.example.com/v1/widgets",
+  method: "myapp.widgets.create",
+  params: { name: "Widget #1" },
+});
+
+await fetch("https://api.example.com/v1/widgets", {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({
+    jsonrpc: "2.0",
+    id: crypto.randomUUID(),
+    method: "myapp.widgets.create",
+    params: { name: "Widget #1", _envelope: envelope },
+  }),
+});
+```
+
+The envelope binds the signature to `(iss, aud, method, params_hash,
+nonce, iat, exp)`, so a single envelope cannot be replayed against a
+different endpoint, method, or payload. Throws
+`AithosSDKError("auth_not_signed_in")` if no owner is loaded; throws
+`AithosSDKError("auth_invalid_sphere")` if you pass a sphere outside
+`"root" | "public" | "circle" | "self"` (default is `"public"`).
+
+Server-side, your backend verifies the envelope with
+`@aithos/protocol-core`'s `verifyEnvelope` (the 9-step check from spec
+§11.4) — same algorithm that `api.aithos.be` uses, no re-implementation
+needed.
+
 ## What lives where
 
-| Namespace        | Purpose                                                                                    |
-| ---------------- | ------------------------------------------------------------------------------------------ |
-| `sdk.compute`    | Bedrock invocation through the Aithos compute proxy (signed envelope, wallet enforcement). |
-| `sdk.wallet`     | Stripe Checkout sessions for credit-pack top-ups, balance helpers.                         |
-| `sdk.ethos`      | Ethos-zone composition / parsing — re-exported from `@aithos/protocol-client`.             |
-| `sdk.onboarding` | First-run identity / DID flows — re-exported.                                              |
-| `sdk.mandates`   | Mint / verify mandates — re-exported.                                                      |
+| Namespace                  | Purpose                                                                                    |
+| -------------------------- | ------------------------------------------------------------------------------------------ |
+| `sdk.auth`                 | Sign-in, sign-up, key custody — and `signEnvelope` for calls to your own Aithos-aware backend. |
+| `sdk.compute`              | Bedrock invocation through the Aithos compute proxy (signed envelope, wallet enforcement). |
+| `sdk.web`                  | Webpage extraction without an LLM through the web extractor proxy (1 mc / call).           |
+| `sdk.wallet`               | Stripe Checkout sessions for credit-pack top-ups, balance helpers.                         |
+| `sdk.ethos`                | Ethos-zone composition / parsing — re-exported from `@aithos/protocol-client`.             |
+| `sdk.onboarding`           | First-run identity / DID flows — re-exported.                                              |
+| `sdk.mandates`             | Mint / verify mandates — re-exported.                                                      |
 
 ## License
 

package/dist/src/assets.d.ts

@@ -0,0 +1,207 @@
+/**
+ * `sdk.assets` — high-level API for the Aithos assets sub-protocol PDS.
+ *
+ * Stores binary content (images, PDFs, audio, video) owned by a
+ * subject, encrypted client-side under per-asset AMKs (Asset Master
+ * Keys), accessible to authorized apps via signed mandates (v0.2).
+ *
+ *     const assets = sdk.assets;
+ *     const avatar = await assets.upload({
+ *       bytes: pngBuffer,
+ *       mediaType: "image/png",
+ *       attachTo: { ethos: { zone: "public", sectionId: "sec_identity" } },
+ *     });
+ *     // avatar.url is a stable CloudFront URL (public asset)
+ *
+ *     const cv = await assets.upload({
+ *       bytes: pdfBuffer,
+ *       mediaType: "application/pdf",
+ *       attachTo: { ethos: { zone: "circle", sectionId: "sec_career_docs" } },
+ *     });
+ *     // cv is private: stored encrypted, fetched via short-lived presigned URL.
+ *
+ *     const bytes = await assets.fetch(cv.urn);
+ *     // decrypted plaintext returned to the caller
+ *
+ * The module wires:
+ *   - AMK generation + wrap (via @aithos/assets-crypto)
+ *   - Bytes encryption with the canonical nonce-prefix on-disk layout
+ *   - RecipientResolver (v0.2-ethos: maps {zone} → recipient set)
+ *   - Direct S3 PUT against the presigned URL returned by init_upload
+ *   - In-memory AMK cache (per asset URN) for sub-second re-fetches
+ *   - Signed envelope JSON-RPC dispatch to /mcp/primitives/{read,write}
+ *
+ * Spec ref: spec/assets/ in the aithos-protocol repo.
+ */
+import { type AssetMetadata, type AssetReference } from "@aithos/assets-crypto";
+export interface CreateAssetsClientArgs {
+    /** Base URL of the deployed assets PDS. */
+    readonly pdsUrl: string;
+    /** Subject DID. */
+    readonly did: string;
+    /** Ed25519 sphere seed (32 bytes). */
+    readonly sphereSeed: Uint8Array;
+    /** Verification method URL within the DID document (e.g. `<did>#<multibase>` for did:key). */
+    readonly verificationMethod: string;
+    /** Optional fetch implementation. Defaults to globalThis.fetch. */
+    readonly fetch?: typeof fetch;
+    /**
+     * Optional override for the recipient resolver. By default the SDK
+     * uses a "self-only" resolver that maps every private upload to the
+     * subject's own X25519 sphere key. Apps that already orchestrate
+     * grantees explicitly may pass a custom resolver.
+     */
+    readonly recipientResolver?: RecipientResolver;
+}
+export interface AttachedContext {
+    readonly ethos?: {
+        readonly zone: "public" | "circle" | "self";
+        readonly sectionId?: string;
+    };
+    readonly data?: {
+        readonly collectionUrn: string;
+        readonly recordId?: string;
+        readonly field?: string;
+    };
+}
+export interface AssetUploadInput {
+    readonly bytes: Uint8Array;
+    readonly mediaType: string;
+    readonly attachTo?: AttachedContext;
+    /**
+     * OPTIONAL — force a regime. Defaults to "auto":
+     *   - ethos.zone === "public" → public
+     *   - anything else → private
+     */
+    readonly regime?: "auto" | "public" | "private";
+    /** OPTIONAL — strict forward secrecy at AMK rotation time. */
+    readonly forwardSecrecy?: "best_effort" | "strict";
+}
+export interface AssetUploadResult {
+    readonly urn: string;
+    readonly assetId: string;
+    readonly mediaType: string;
+    readonly sizeBytes: number;
+    readonly sha256OfPlaintext: string;
+    readonly encrypted: boolean;
+    /**
+     * Stable URL for public assets (CloudFront-served). Absent for
+     * private assets — fetch them via {@link AssetsClient.fetch}.
+     */
+    readonly url?: string;
+    /** Whether this URN was returned by intra-subject dedup (existing asset). */
+    readonly dedupHit: boolean;
+}
+export interface AssetFetchResult {
+    readonly urn: string;
+    readonly mediaType: string;
+    readonly sizeBytes: number;
+    readonly bytes: Uint8Array;
+    readonly sha256OfPlaintext: string;
+}
+export interface AssetBrief {
+    readonly urn: string;
+    readonly assetId: string;
+    readonly mediaType: string;
+    readonly sizeBytes: number;
+    readonly sha256OfPlaintext: string;
+    readonly encrypted: boolean;
+    readonly state: "ACTIVE" | "ORPHANED" | "TOMBSTONED";
+    readonly referenceCount: number;
+    readonly createdAt: string;
+    readonly modifiedAt: string;
+}
+export interface ListAssetsOpts {
+    readonly filter?: {
+        readonly mediaTypePrefix?: string;
+        readonly sizeBytes?: {
+            gte?: number;
+            lte?: number;
+        };
+        readonly createdAfter?: string;
+        readonly createdBefore?: string;
+    };
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly order?: "newest" | "oldest";
+    readonly includeOrphaned?: boolean;
+    readonly includeTombstoned?: boolean;
+}
+export interface ThumbnailUploadInput extends AssetUploadInput {
+    /** Long-edge sizes to produce (e.g. [64, 256]). */
+    readonly sizes: readonly number[];
+    /**
+     * Downscaler. The SDK does NOT bundle an image library; callers pass
+     * a function that takes the original bytes and a target size and
+     * returns downscaled bytes. Typical implementations: `pica` in the
+     * browser, `sharp` in Node.
+     */
+    readonly downscale: (bytes: Uint8Array, targetLongEdge: number) => Promise<Uint8Array>;
+}
+export interface ThumbnailUploadResult {
+    readonly primary: AssetUploadResult;
+    readonly thumbnails: readonly {
+        size: number;
+        result: AssetUploadResult;
+    }[];
+}
+/**
+ * Maps an attaching context to the set of recipients whose wraps the
+ * AMK must carry. The v0.1 default returns the subject's own X25519
+ * sphere key derived from the SDK's seed.
+ *
+ * v0.2 will introduce an Ethos-aware resolver that inspects the
+ * current manifest's `zones.<z>.cipher.wraps[]` (or, in v0.3, the
+ * per-section wraps) to mirror grantees on attached assets.
+ */
+export interface RecipientResolver {
+    resolve(input: {
+        subjectDid: string;
+        context: AttachedContext | undefined;
+    }): Promise<RecipientSet>;
+}
+export interface RecipientSet {
+    readonly recipients: ReadonlyArray<{
+        readonly didUrl: string;
+        readonly x25519PublicKey: Uint8Array;
+    }>;
+}
+export declare function createAssetsClient(args: CreateAssetsClientArgs): AssetsClient;
+export declare class AssetsClient {
+    #private;
+    constructor(args: CreateAssetsClientArgs);
+    upload(input: AssetUploadInput): Promise<AssetUploadResult>;
+    /**
+     * Upload a primary asset plus one or more thumbnails (downscaled
+     * client-side). Convenience method for the Deep avatar use case and
+     * any UI that displays the same asset at multiple resolutions.
+     *
+     * The thumbnails are attached to the same context as the primary
+     * and uploaded in parallel. They carry the {@link AssetReference}
+     * role `"thumbnail"` when referenced from a section (see
+     * spec/assets/03-asset-descriptors.md §3.2.3).
+     */
+    uploadWithThumbnails(input: ThumbnailUploadInput): Promise<ThumbnailUploadResult>;
+    fetch(urn: string): Promise<AssetFetchResult>;
+    head(urn: string): Promise<AssetMetadata>;
+    list(opts?: ListAssetsOpts): Promise<{
+        items: AssetBrief[];
+        nextCursor?: string;
+    }>;
+    ref(urn: string, reference: AssetReference): Promise<{
+        referenceCount: number;
+        gammaRef: string;
+    }>;
+    unref(urn: string, reference: AssetReference): Promise<{
+        referenceCount: number;
+        gammaRef: string;
+    }>;
+    listReferences(urn: string): Promise<AssetReference[]>;
+    delete(urn: string): Promise<{
+        tombstonedAt: string;
+        gammaRef: string;
+    }>;
+    /** Zero in-memory AMK cache. Useful at user logout. */
+    reset(): void;
+}
+//# sourceMappingURL=assets.d.ts.map