@atlastodo/sdk 0.1.11-rc.7 → 0.1.11-rc.9

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./client.js";
+export * from "./vault.js";
 export { InvalidApiTokenError } from "@atlastodo/client-core";
 export * from "./dates.js";

package/dist/index.js

@@ -310,6 +310,219 @@ function checkPriority(p) {
 function lockedError(id) {
   return new AtlasError("task_locked", `task "${id}" is in a shared project whose key this token cannot open`);
 }
+// src/vault.ts
+import {
+  ApiClient as ApiClient2,
+  Keyring as Keyring2,
+  LocalStore as LocalStore2,
+  SyncClient as SyncClient2,
+  assertServerCompatible,
+  deriveApiTokenKeys as deriveApiTokenKeys2,
+  getPublicKey,
+  parseApiToken as parseApiToken2,
+  unwrapApiTokenAppKeys
+} from "@atlastodo/client-core";
+import {
+  VAULT_ITEM_TYPES,
+  VaultError,
+  newVaultItemFields,
+  resolveVaultItem,
+  summarizeVaultItem,
+  toVaultItem,
+  vaultItemChanges,
+  vaultItemField
+} from "@atlastodo/shared";
+var VAULT_APP = "vault";
+var sameName = (a, b) => a.trim().toLowerCase() === b.trim().toLowerCase();
+function byNameThenId(a, b) {
+  const [an, bn] = [a.name.toLowerCase(), b.name.toLowerCase()];
+  if (an !== bn)
+    return an < bn ? -1 : 1;
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+function rules(run) {
+  try {
+    return run();
+  } catch (e) {
+    if (e instanceof VaultError)
+      throw new AtlasError(e.code, e.message);
+    throw e;
+  }
+}
+
+class VaultClient {
+  store;
+  sync;
+  userId;
+  canWrite;
+  expiresAt;
+  constructor(store, sync, userId, canWrite, expiresAt) {
+    this.store = store;
+    this.sync = sync;
+    this.userId = userId;
+    this.canWrite = canWrite;
+    this.expiresAt = expiresAt;
+  }
+  static async connect(opts) {
+    const parts = parseApiToken2(opts.token);
+    const { auth } = deriveApiTokenKeys2(parts);
+    const api = new ApiClient2({
+      baseUrl: opts.serverUrl.replace(/\/+$/, ""),
+      fetch: opts.fetch,
+      apps: [VAULT_APP],
+      reauthenticate: async () => (await api.openApiTokenSession(parts.id, auth)).access_token
+    });
+    if (opts.checkServer ?? true) {
+      assertServerCompatible(await api.getDiscovery(), {
+        minProtocol: 6,
+        capabilities: ["api_tokens", "app_scoped_sync", "app_scoped_api_tokens"],
+        apps: [VAULT_APP]
+      });
+    }
+    const session = await api.openApiTokenSession(parts.id, auth);
+    const apps = session.apps ?? ["todo"];
+    const wraps = session.app_keys?.[VAULT_APP];
+    if (!apps.includes(VAULT_APP) || !wraps) {
+      throw new AtlasError("app_not_in_token", `this API token is not for Atlas Vault (it is for ${apps.join(", ")}); make a token that includes it`);
+    }
+    api.setTokens(session.access_token);
+    const { appKey, privateKey } = unwrapApiTokenAppKeys(parts, session.user_id, VAULT_APP, wraps);
+    api.setKeyring(new Keyring2({ dek: appKey, privateKey, publicKey: getPublicKey(privateKey) }));
+    api.setLegacyMigrated(true);
+    const store = new LocalStore2(parts.id, { newId: () => globalThis.crypto.randomUUID() });
+    api.setScopeContext(store, session.user_id);
+    const sync = new SyncClient2(store, api, { cursor: 0 });
+    const client = new VaultClient(store, sync, session.user_id, session.write ?? true, session.expires_at ?? null);
+    await client.syncOrThrow();
+    return client;
+  }
+  async syncOrThrow() {
+    const result = await this.sync.sync();
+    if (result.skipped) {
+      throw new AtlasError("sync_skipped", `sync did not run (${result.skipped}); try again later`);
+    }
+  }
+  async push() {
+    await this.syncOrThrow();
+    const pending = this.store.unsyncedOps().length;
+    if (pending > 0) {
+      throw new AtlasError("not_pushed", `${pending} change(s) did not reach the server`);
+    }
+  }
+  requireWrite() {
+    if (!this.canWrite) {
+      throw new AtlasError("api_token_read_only", "this API token is read-only: changing Atlas Vault data needs a token made with write access");
+    }
+  }
+  allItems() {
+    return this.store.list("vault.item").map((e) => toVaultItem(e.id, e.fields));
+  }
+  folderName(id) {
+    const f = id ? this.store.get("vault.folder", id) : null;
+    return f && typeof f.name === "string" ? f.name : null;
+  }
+  view(item) {
+    return { ...item, folder_name: this.folderName(item.folder) };
+  }
+  summaryView(item) {
+    return { ...summarizeVaultItem(item), folder_name: this.folderName(item.folder) };
+  }
+  folders() {
+    return this.store.list("vault.folder").map((e) => ({
+      id: e.id,
+      name: typeof e.fields.name === "string" ? e.fields.name : "",
+      created_at: typeof e.fields.created_at === "number" ? e.fields.created_at : 0,
+      updated_at: typeof e.fields.updated_at === "number" ? e.fields.updated_at : 0,
+      deleted_at: typeof e.fields.deleted_at === "number" ? e.fields.deleted_at : null
+    })).filter((f) => f.deleted_at == null).sort(byNameThenId);
+  }
+  folderId(ref) {
+    const r = ref.trim();
+    const folders = this.folders();
+    const byId = folders.find((f) => f.id === r);
+    if (byId)
+      return byId.id;
+    const named = folders.filter((f) => sameName(f.name, r));
+    if (named.length === 1)
+      return named[0].id;
+    if (named.length === 0)
+      throw new AtlasError("unknown_vault_folder", `no vault folder "${r}"`);
+    throw new AtlasError("ambiguous_vault_folder", `"${r}" names ${named.length} vault folders; use an id`);
+  }
+  itemId(ref) {
+    return rules(() => resolveVaultItem(this.allItems(), ref));
+  }
+  item(ref) {
+    const id = this.itemId(ref);
+    return this.view(toVaultItem(id, this.store.get("vault.item", id) ?? {}));
+  }
+  secret(ref, field) {
+    const item = this.item(ref);
+    return rules(() => vaultItemField(item, field));
+  }
+  items(query = {}) {
+    const folder = query.folder ? this.folderId(query.folder) : null;
+    if (query.type && !VAULT_ITEM_TYPES.includes(query.type)) {
+      throw new AtlasError("bad_input", `type must be one of ${VAULT_ITEM_TYPES.join(", ")}`);
+    }
+    const tag = query.tag?.toLowerCase();
+    const search = query.search?.toLowerCase();
+    return this.allItems().filter((i) => i.deleted_at == null).filter((i) => folder == null || i.folder === folder).filter((i) => !query.type || i.type === query.type).filter((i) => !tag || i.tags.some((t) => t.toLowerCase() === tag)).filter((i) => !search || i.name.toLowerCase().includes(search) || i.urls.some((u) => u.toLowerCase().includes(search)) || i.tags.some((t) => t.toLowerCase().includes(search))).sort(byNameThenId).map((i) => this.summaryView(i));
+  }
+  withFolderId(input) {
+    return typeof input.folder === "string" ? { ...input, folder: this.folderId(input.folder) } : input;
+  }
+  write(entity, id, fields) {
+    for (const [field, value] of Object.entries(fields))
+      this.store.set(entity, id, field, value);
+  }
+  async createItem(input) {
+    this.requireWrite();
+    const fields = rules(() => newVaultItemFields(this.withFolderId(input), Date.now()));
+    const id = this.store.newEntityId();
+    this.write("vault.item", id, fields);
+    await this.push();
+    return this.item(id);
+  }
+  async updateItem(ref, patch) {
+    const id = this.itemId(ref);
+    this.requireWrite();
+    const current = this.store.get("vault.item", id) ?? {};
+    const changes = rules(() => vaultItemChanges(current, this.withFolderId(patch), Date.now()));
+    if (Object.keys(changes).length) {
+      this.write("vault.item", id, changes);
+      await this.push();
+    }
+    return this.item(id);
+  }
+  async deleteItem(ref) {
+    const id = this.itemId(ref);
+    if (this.item(id).deleted_at != null)
+      return id;
+    this.requireWrite();
+    const now = Date.now();
+    this.write("vault.item", id, { deleted_at: now, updated_at: now });
+    await this.push();
+    return id;
+  }
+  async createFolder(name) {
+    this.requireWrite();
+    const trimmed = name.trim();
+    if (!trimmed)
+      throw new AtlasError("bad_input", "a vault folder needs a name");
+    if (this.folders().some((f) => sameName(f.name, trimmed))) {
+      throw new AtlasError("vault_folder_exists", `there is already a vault folder "${trimmed}"`);
+    }
+    const now = Date.now();
+    const id = this.store.newEntityId();
+    this.write("vault.folder", id, { name: trimmed, created_at: now, updated_at: now });
+    await this.push();
+    return this.folders().find((f) => f.id === id);
+  }
+  close() {
+    this.sync.dispose();
+  }
+}
 
 // src/index.ts
 import { InvalidApiTokenError } from "@atlastodo/client-core";
@@ -368,5 +581,7 @@ export {
   AtlasClient,
   AtlasError,
   InvalidApiTokenError,
+  VAULT_APP,
+  VaultClient,
   parseDue
 };

package/dist/testing.d.ts

@@ -1,11 +1,28 @@
 import { LocalStore, SyncClient, type FetchLike, type WireOp } from "@atlastodo/client-core";
 export declare const USER_ID = "01920000-0000-7000-8000-0000000000aa";
+export interface FakeServerOptions {
+    /** The apps the token is for; todo by default. */
+    apps?: readonly string[];
+    /** The apps `GET /discovery` offers; without it the server predates discovery (404). */
+    offers?: readonly string[];
+    /** Whether the token may write (`write` of the session); a push is 403 when it may not. */
+    write?: boolean;
+    /** The token's `expires_at` (unix ms) in the session response. */
+    expiresAt?: number;
+}
 /**
  * A stand-in for the server's sync surface: one account's op log, kept as the opaque wire ops the
  * clients push (ciphertext), like the real server. Enough of the API for the SDK and an app-like
  * second client.
+ *
+ * Its token is for todo unless made for other `apps`, each with a fresh key and identity. Sync
+ * requests are scoped as the server scopes a token session (`x-atlas-sync-apps`, todo when
+ * absent): an app the token is not for is 403 `app_not_enabled`, pull and the snapshot serve only
+ * the scope's ops. A read-only token's push is 403 `api_token_read_only`; once {@link expired},
+ * the exchange and every request are 401 `api_token_expired`.
  */
 export declare class FakeServer {
+    private readonly opts;
     readonly ops: (WireOp & {
         seq: number;
     })[];
@@ -15,8 +32,19 @@ export declare class FakeServer {
         dek: Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>;
         privateKey: Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>;
     };
+    readonly apps: readonly string[];
+    /** Every other app's key and X25519 private key, by app. */
+    readonly appKeys: Record<string, {
+        appKey: Uint8Array;
+        privateKey: Uint8Array;
+    }>;
     sessions: number;
     revoked: boolean;
+    expired: boolean;
+    write: boolean;
+    /** The `x-atlas-sync-apps` header of every `/sync/*` request (null when absent). */
+    readonly syncApps: (string | null)[];
+    constructor(opts?: FakeServerOptions);
     tokenString(): string;
     fetch: FetchLike;
     /** A signed-in app device of the same account, for writes the SDK should see. */

package/dist/testing.js

@@ -4,21 +4,39 @@ import {
   LocalStore,
   SyncClient,
   Keyring,
+  SYNC_APPS_HEADER,
+  appOfKind,
   deriveApiTokenKeys,
   formatApiToken,
   generateApiToken,
   randomBytes,
+  wrapAppKeysForApiToken,
   wrapKeysForApiToken
 } from "@atlastodo/client-core";
 var USER_ID = "01920000-0000-7000-8000-0000000000aa";
 
 class FakeServer {
+  opts;
   ops = [];
   seq = 0;
   token = generateApiToken();
   keys = { dek: randomBytes(32), privateKey: randomBytes(32) };
+  apps;
+  appKeys = {};
   sessions = 0;
   revoked = false;
+  expired = false;
+  write;
+  syncApps = [];
+  constructor(opts = {}) {
+    this.opts = opts;
+    this.apps = opts.apps ?? ["todo"];
+    this.write = opts.write ?? true;
+    for (const app of this.apps) {
+      if (app !== "todo")
+        this.appKeys[app] = { appKey: randomBytes(32), privateKey: randomBytes(32) };
+    }
+  }
   tokenString() {
     return formatApiToken(this.token);
   }
@@ -26,37 +44,89 @@ class FakeServer {
     const u = new URL(String(url));
     const body = init?.body ? JSON.parse(String(init.body)) : undefined;
     const json = (status, data) => new Response(data === undefined ? null : JSON.stringify(data), { status });
-    const authed = init?.headers?.authorization;
+    const headers = init?.headers ?? {};
+    const authed = headers.authorization;
+    const expired = () => json(401, { error: "this API token has expired", code: "api_token_expired" });
     switch (`${init?.method} ${u.pathname}`) {
+      case "GET /discovery": {
+        if (!this.opts.offers)
+          return json(404, { error: "not found" });
+        return json(200, {
+          service: "atlas-server",
+          version: "0.2.0",
+          protocol_version: 6,
+          min_protocol_version: 6,
+          capabilities: [
+            "api_tokens",
+            "app_manifests",
+            "account_apps",
+            "root_key",
+            "app_scoped_sync",
+            "app_scoped_api_tokens",
+            "api_token_policies"
+          ],
+          apps: this.opts.offers.map((id) => ({ id, name: id, version: 1 }))
+        });
+      }
       case "POST /auth/api-token/session": {
         if (this.revoked || body.token_id !== this.token.id || body.auth !== deriveApiTokenKeys(this.token).auth) {
           return json(401, { error: "unauthorized" });
         }
+        if (this.expired)
+          return expired();
         this.sessions++;
+        const appKeys = Object.fromEntries(Object.entries(this.appKeys).map(([app, keys]) => [
+          app,
+          wrapAppKeysForApiToken(this.token, USER_ID, app, keys)
+        ]));
         return json(200, {
           access_token: `access-${this.sessions}`,
           expires_in: 900,
           token_id: this.token.id,
           user_id: USER_ID,
-          ...wrapKeysForApiToken(this.token, USER_ID, this.keys)
+          apps: this.apps,
+          write: this.write,
+          ...this.opts.expiresAt !== undefined ? { expires_at: this.opts.expiresAt } : {},
+          ...this.apps.includes("todo") ? wrapKeysForApiToken(this.token, USER_ID, this.keys) : {},
+          ...Object.keys(appKeys).length ? { app_keys: appKeys } : {}
         });
       }
     }
     if (this.revoked || !authed?.startsWith("Bearer "))
       return json(401, { error: "unauthorized" });
+    if (this.expired)
+      return expired();
+    const scopeHeader = headers[SYNC_APPS_HEADER] ?? null;
+    const scope = scopeHeader ? scopeHeader.split(",").map((a) => a.trim()) : ["todo"];
+    const inScope = (op) => scope.includes(appOfKind(op.entity)?.app ?? "");
+    if (u.pathname.startsWith("/sync/")) {
+      this.syncApps.push(scopeHeader);
+      const outside = scope.find((a) => !this.apps.includes(a));
+      if (outside) {
+        return json(403, { code: "app_not_enabled", app: outside, scope: "token", error: "no" });
+      }
+    }
     switch (`${init?.method} ${u.pathname}`) {
       case "GET /sync/snapshot":
-        return json(200, { operations: this.ops, cursor: this.seq });
+        return json(200, { operations: this.ops.filter(inScope), cursor: this.seq });
       case "GET /sync/pull": {
         const since = Number(u.searchParams.get("since"));
         const page = this.ops.filter((o) => o.seq > since).slice(0, 500);
         return json(200, {
-          operations: page,
+          operations: page.filter(inScope),
           from: since,
           cursor: page.length ? page[page.length - 1].seq : Math.max(since, this.seq)
         });
       }
       case "POST /sync/push": {
+        if (!this.write) {
+          return json(403, { error: "this API token is read-only", code: "api_token_read_only" });
+        }
+        const outside = body.operations.find((op) => !inScope(op));
+        if (outside) {
+          const app = appOfKind(outside.entity)?.app ?? "unknown";
+          return json(403, { code: "app_not_enabled", app, scope: "session", error: "no" });
+        }
         const from = this.seq;
         for (const op of body.operations) {
           if (this.ops.some((o) => o.id === op.id))

package/dist/vault.d.ts

@@ -0,0 +1,91 @@
+import { type FetchLike } from "@atlastodo/client-core";
+import { type VaultItem, type VaultItemInput, type VaultItemPatch, type VaultItemSummary } from "@atlastodo/shared";
+/**
+ * A headless Atlas Vault client for integrations and CI, signed in with an API token that includes
+ * the vault (`apps: ["vault"]`). Like `AtlasClient` for todo, `connect` unwraps the vault key the
+ * token carries and pulls the vault into memory, decrypting it here: the server only ever sees
+ * ciphertext, and reads none of an item's fields. Every sync request names the vault
+ * (`x-atlas-sync-apps`). The item rules are `@atlastodo/shared`'s, at parity with the `atlas`
+ * CLI's (the shared vault item test vectors).
+ *
+ * A vault token is read-only unless it was made with write access, and always expires; a write on
+ * a read-only token fails with `api_token_read_only` before anything is written, and an expired
+ * token fails to connect with the server's `api_token_expired`.
+ */
+export declare const VAULT_APP = "vault";
+export interface VaultConnectOptions {
+    /** The Atlas server, e.g. `https://app.atlastodo.dev` (an `/api` suffix is fine too). */
+    serverUrl: string;
+    /** An `atlas_pat_…` token that includes Atlas Vault. */
+    token: string;
+    fetch?: FetchLike;
+    /** Check `GET /discovery` first (default true): a server without the vault fails clearly. */
+    checkServer?: boolean;
+}
+export interface VaultFolder {
+    id: string;
+    name: string;
+    created_at: number;
+    updated_at: number;
+    deleted_at: number | null;
+}
+export interface VaultQuery {
+    /** A folder id or name (case-insensitive). */
+    folder?: string;
+    /** An item type. */
+    type?: string;
+    /** A tag, case-insensitive. */
+    tag?: string;
+    /** Case-insensitive substring of the name, a URL or a tag. */
+    search?: string;
+}
+/** An item with its folder's name. */
+export type VaultItemView = VaultItem & {
+    folder_name: string | null;
+};
+/** A listed item with its folder's name: no secret values. */
+export type VaultItemSummaryView = VaultItemSummary & {
+    folder_name: string | null;
+};
+export declare class VaultClient {
+    private readonly store;
+    private readonly sync;
+    readonly userId: string;
+    /** Whether the token may write. */
+    readonly canWrite: boolean;
+    /** When the token expires (unix ms), if the server said. */
+    readonly expiresAt: number | null;
+    private constructor();
+    static connect(opts: VaultConnectOptions): Promise<VaultClient>;
+    private syncOrThrow;
+    private push;
+    private requireWrite;
+    private allItems;
+    private folderName;
+    private view;
+    private summaryView;
+    /** Folders outside the trash, by name. */
+    folders(): VaultFolder[];
+    private folderId;
+    /** The id of the item `ref` names: an id, or a unique name outside the trash. */
+    itemId(ref: string): string;
+    /** One item by id or name, secrets included. */
+    item(ref: string): VaultItemView;
+    /** One field's value of the item `ref` names: what a CI step reads. */
+    secret(ref: string, field: string): string;
+    /** Items outside the trash, filtered by `query`, without their secrets: by name. */
+    items(query?: VaultQuery): VaultItemSummaryView[];
+    /** `input` with its `folder` (an id or name) resolved to the folder's id. */
+    private withFolderId;
+    private write;
+    /** Create an item (its `folder` may be a name) and push it. */
+    createItem(input: VaultItemInput): Promise<VaultItemView>;
+    /** Change the item `ref` names and push; unchanged values write nothing. */
+    updateItem(ref: string, patch: VaultItemPatch): Promise<VaultItemView>;
+    /** Move the item `ref` names to the trash; a no-op when it already is. Returns its id. */
+    deleteItem(ref: string): Promise<string>;
+    /** Create a folder and push it. */
+    createFolder(name: string): Promise<VaultFolder>;
+    /** Stop background timers. Every write has already been pushed. */
+    close(): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlastodo/sdk",
-  "version": "0.1.11-rc.7",
+  "version": "0.1.11-rc.9",
   "description": "Headless Atlas client for integrations: signs in with a personal API token and syncs an account's tasks into memory",
   "license": "AGPL-3.0-only",
   "homepage": "https://github.com/atlastodo/atlas/tree/main/packages/sdk",
@@ -47,8 +47,8 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@atlastodo/client-core": "0.1.11-rc.7",
-    "@atlastodo/shared": "0.1.11-rc.7"
+    "@atlastodo/client-core": "0.1.11-rc.9",
+    "@atlastodo/shared": "0.1.11-rc.9"
   },
   "devDependencies": {
     "@types/node": "^26.6.5",