@aithos/sdk 0.1.0-alpha.5 → 0.1.0-alpha.51

package/README.md

@@ -55,15 +55,253 @@ const reply = await sdk.compute.invokeBedrock({
 console.log(reply.content);
 ```
 
+## Transcribing audio → text
+
+`sdk.compute.invokeTranscribe` turns an audio `Blob` into text through AWS
+Transcribe. It does one thing — audio → text — and **stores nothing**: it
+returns the transcript and you decide what to do with it (write it to an
+ethos, a PDS, your own database, email it, or throw it away).
+
+```ts
+// Browser: a Blob from MediaRecorder; backend: a Blob from a Buffer.
+const result = await sdk.compute.invokeTranscribe({
+  audio: blob,                          // Blob/File (Node 18+ has global Blob)
+  model: "transcribe:aws-fr-standard",  // default; also aws-en-standard
+  languageCode: "fr-FR",                // optional
+  // durationSecOverride: 127,          // REQUIRED on backends (no DOM probe)
+  onProgress: (s) => console.log(s.phase), // uploading → starting → processing → completed
+});
+
+console.log(result.text);          // "Bonjour, je voulais te dire que…"
+console.log(result.segments);      // [{ start_sec, end_sec, text }]
+console.log(result.creditsCharged);
+
+// Then YOU choose where it goes — the compute has no opinion:
+await myEthos.addRevision(result.text);   // or PDS, DB, email, nothing…
+```
+
+The core is isomorphic (Node + browser) and depends only on `Blob`, `fetch`
+and timers. Browser-only resilience is opt-in and framework-agnostic:
+`sdk.compute.transcribeDraft` (IndexedDB queue of recordings) and
+`sdk.compute.listLocalPendingTranscribes()` /
+`subscribeLocalPendingTranscribes()` / `resumeTranscribe(jobId)` recover jobs
+across reloads. React users get `useAithosTranscribePendingJobs(sdk.compute)`
+from `@aithos/sdk/react`. Advanced callers can drive the flow manually with
+`prepareTranscribe` / `startTranscribe` / `getTranscribeStatus`.
+
+## 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/apps.d.ts

@@ -0,0 +1,224 @@
+import type { AithosAuth } from "./auth.js";
+import type { AithosSdkEndpoints } from "./endpoints.js";
+/**
+ * The audience set scopes which consumers are eligible. `"open"` lets
+ * any DID invoke the app; `"list"` restricts to an explicit allowlist.
+ */
+export type AudienceSet = "open" | "list";
+export interface SponsorshipBudgetInput {
+    /**
+     * Authority-interpreted unit of account. Default `"aithos.mc"` (the
+     * platform microcredit, ≈ €0.001 of AWS pass-through cost). Authorities
+     * MAY accept other units — see draft §13.3.4.
+     */
+    readonly unit?: string;
+    /** Lifetime cap per consumer, in `unit`. */
+    readonly perUserCap: number;
+    /** If set, the per-user cap applies over a sliding window. */
+    readonly perUserWindowSeconds?: number | null;
+    /** UTC-day cap on total sponsored consumption across all consumers. */
+    readonly perDayTotalCap: number;
+    /** Lifetime pool cap across all consumers. `null` ≡ no cap. */
+    readonly poolCapTotal?: number | null;
+}
+export interface SponsorshipAudienceInput {
+    /** App DID the sponsorship covers (typically `sdk.appDid`). */
+    readonly appDid: string;
+    readonly audienceSet: AudienceSet;
+    /** Required iff `audienceSet === "list"`. */
+    readonly consumers?: readonly string[];
+}
+export interface SponsorshipAccountingAuthorityInput {
+    readonly did: string;
+    readonly endpoint: string;
+}
+export interface CreateSponsorshipMandateArgs {
+    readonly audience: SponsorshipAudienceInput;
+    readonly scopes: readonly string[];
+    readonly allowedMethods: readonly string[];
+    readonly allowedModels?: readonly string[];
+    readonly budget: SponsorshipBudgetInput;
+    readonly accountingAuthority: SponsorshipAccountingAuthorityInput;
+    /** Defaults to now. */
+    readonly notBefore?: Date;
+    /** Defaults to 365 days. */
+    readonly ttlSeconds?: number;
+}
+/**
+ * Signed sponsorship mandate, ready to seed into the authority's
+ * `aithos-app-sponsorships` table. Same shape as
+ * `@aithos/protocol-core`'s `SponsorshipMandate`.
+ */
+export interface SignedSponsorshipMandate {
+    readonly "aithos-sponsorship-mandate": "0.1.0";
+    readonly id: string;
+    readonly issuer: string;
+    readonly issued_by_key: string;
+    readonly audience: {
+        readonly app_did: string;
+        readonly audience_set: AudienceSet;
+        readonly consumers?: readonly string[];
+    };
+    readonly scopes: readonly string[];
+    readonly allowed_methods: readonly string[];
+    readonly allowed_models?: readonly string[];
+    readonly budget: {
+        readonly unit: string;
+        readonly per_user_cap: number;
+        readonly per_user_window_seconds: number | null;
+        readonly per_day_total_cap: number;
+        readonly pool_cap_total: number | null;
+    };
+    readonly accounting_authority: {
+        readonly did: string;
+        readonly endpoint: string;
+    };
+    readonly not_before: string;
+    readonly not_after: string;
+    readonly issued_at: string;
+    readonly nonce: string;
+    readonly signature: {
+        readonly alg: "ed25519";
+        readonly key: string;
+        readonly value: string;
+    };
+}
+export interface SignedSponsorshipRevocation {
+    readonly "aithos-revocation": "0.1.0";
+    readonly mandate_id: string;
+    readonly mandate_kind: "sponsorship-mandate";
+    readonly issuer: string;
+    readonly issued_by_key: string;
+    readonly revoked_at: string;
+    readonly reason: string;
+    readonly signature: {
+        readonly alg: "ed25519";
+        readonly key: string;
+        readonly value: string;
+    };
+}
+export type AppCreditPackId = "app-credits-10k" | "app-credits-50k" | "app-credits-200k";
+export interface CreateAppTopupSessionArgs {
+    /** Which app-credits pack to purchase. */
+    readonly packId: AppCreditPackId;
+    /** Where Stripe redirects after a successful payment. */
+    readonly successUrl: string;
+    /** Where Stripe redirects if the user cancels. */
+    readonly cancelUrl: string;
+    /** Abort signal to cancel the request. */
+    readonly signal?: AbortSignal;
+}
+export interface CreateAppTopupSessionResult {
+    readonly checkoutUrl: string;
+    readonly sessionId: string;
+}
+export interface AppsNamespaceDeps {
+    readonly auth: AithosAuth;
+    readonly appDid: string;
+    readonly endpoints: AithosSdkEndpoints;
+    readonly fetch: typeof fetch;
+}
+export declare class AppsNamespace {
+    #private;
+    constructor(deps: AppsNamespaceDeps);
+    /**
+     * Build and sign a `SponsorshipMandate` as the calling owner. The
+     * returned JSON is signed by the owner's `#public` sphere key, ready
+     * to be seeded into the authority's `aithos-app-sponsorships` table.
+     *
+     * V0.1 has no server endpoint — get the row into DDB via:
+     *   1. `aws dynamodb put-item --table-name aithos-app-sponsorships
+     *      --item file://mandate.json` (raw), or
+     *   2. The ops bootstrap script in
+     *      `innoesate/aithos/platform/scripts/seed-sponsorship.mjs`
+     *      (planned for V0.2).
+     *
+     * Hash with `sponsorshipMandateHash()` from `@aithos/protocol-core`
+     * if you need to embed it in an envelope's `sponsorship.hash` field.
+     */
+    createSponsorshipMandate(args: CreateSponsorshipMandateArgs): Promise<SignedSponsorshipMandate>;
+    /**
+     * Build and sign a §4.6 revocation document targeting a sponsorship
+     * mandate. Same upload caveat as `createSponsorshipMandate`.
+     */
+    revokeSponsorshipMandate(mandate: SignedSponsorshipMandate, reason: string): Promise<SignedSponsorshipRevocation>;
+    /**
+     * Stripe Checkout session for an `app-credits-*` pack. The session is
+     * bound to the calling owner's DID (which is treated as the app's
+     * funding DID — Option A unified wallet, see plan §3.4).
+     *
+     * Same endpoint and auth pattern as `sdk.wallet.createTopupSession`,
+     * just with the app-credits pack id family.
+     */
+    createAppTopupSession(args: CreateAppTopupSessionArgs): Promise<CreateAppTopupSessionResult>;
+    /**
+     * Build, sign, and PUBLISH a SponsorshipMandate to the authority's
+     * `aithos-app-sponsorships` table via `aithos.sponsorship_create`.
+     *
+     * Combines local signing (see {@link createSponsorshipMandate}) with the
+     * server upload step. After this resolves, the sponsorship is active —
+     * the next `sdk.compute.invokeBedrock` call targeting `args.audience.appDid`
+     * may be sponsored (subject to caps).
+     *
+     * Requires that the calling owner is the registered `owner_did` of
+     * `args.audience.appDid` in `aithos-auth-apps`; otherwise the server
+     * rejects with `-32042` "not the owner".
+     */
+    publishSponsorship(args: CreateSponsorshipMandateArgs): Promise<{
+        mandate: SignedSponsorshipMandate;
+        sponsorshipId: string;
+        mandateHash: string;
+        status: "active";
+        createdAt: number;
+    }>;
+    /**
+     * Read the active sponsorship for an app. Open endpoint (no envelope
+     * required): the mandate is publicly signed and resolvable anyway.
+     *
+     * Returns `{ exists: false }` when no row exists for the app.
+     */
+    getSponsorship(args: {
+        appDid: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        exists: false;
+    } | {
+        exists: true;
+        sponsorshipId: string;
+        mandate: SignedSponsorshipMandate;
+        mandateHash: string;
+        status: "active" | "paused" | "depleted" | "expired" | "revoked";
+        poolConsumedLifetime: number;
+        createdAt: number;
+        lastUpdatedAt: number;
+    }>;
+    /**
+     * Revoke a published sponsorship by `app_did` + `sponsorship_id`. The
+     * row is marked `status: "revoked"` server-side; the routing cache is
+     * invalidated so the next compute call falls back to the user wallet.
+     */
+    revokeSponsorship(args: {
+        appDid: string;
+        sponsorshipId: string;
+        reason: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        status: "revoked";
+    }>;
+    /**
+     * Read the app's wallet balance (= the sponsor pool). Requires owner
+     * signature.
+     */
+    getAppWalletBalance(args: {
+        appDid: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        appDid: string;
+        exists: boolean;
+        balance: number;
+        balancePurchase: number;
+        balanceGrant: number;
+        dailySpent: number;
+    }>;
+}
+//# sourceMappingURL=apps.d.ts.map