imprint-mcp 0.2.0

package/src/imprint/cookie-jar.ts

@@ -0,0 +1,246 @@
+/**
+ * Minimal browser-compatible cookie jar for replay.
+ *
+ * This is the minimal compatible wrapper for the v1 state model. It keeps the
+ * needed surface small: Set-Cookie ingestion, request-url matching, path
+ * ordering, deletion, and ambiguity detection for scalar `${cookie.*}` lookups.
+ * `tough-cookie` can replace this after an audit of browser-compatibility,
+ * ESM/Bun support, public suffix behavior, license, and security history.
+ * CHIPS/partitioned cookies and full SameSite context enforcement are out of
+ * scope for v1.
+ */
+
+export interface RuntimeCookie {
+  name: string;
+  value: string;
+  domain: string;
+  path: string;
+  expires?: number;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: string;
+  hostOnly?: boolean;
+  creationIndex?: number;
+}
+
+export interface CookieLookupConstraints {
+  url?: string;
+  domain?: string;
+  path?: string;
+  sameSite?: string;
+  allowHttpOnlyProjection?: boolean;
+}
+
+type CookieLookupResult =
+  | { ok: true; cookie: RuntimeCookie }
+  | { ok: false; reason: 'missing' | 'ambiguous' | 'httponly'; matches: RuntimeCookie[] };
+
+let globalCreationIndex = 0;
+
+export class RuntimeCookieJar {
+  private cookies: RuntimeCookie[] = [];
+
+  constructor(cookies: RuntimeCookie[] = []) {
+    for (const c of cookies) this.setCookie(c);
+  }
+
+  clone(): RuntimeCookieJar {
+    return new RuntimeCookieJar(this.cookies.map((c) => ({ ...c })));
+  }
+
+  toJSON(): RuntimeCookie[] {
+    return this.cookies.map((c) => ({ ...c }));
+  }
+
+  setCookie(cookie: RuntimeCookie): void {
+    const normalized = normalizeCookie(cookie);
+    const idx = this.cookies.findIndex(
+      (c) =>
+        c.name === normalized.name && c.domain === normalized.domain && c.path === normalized.path,
+    );
+
+    if (isExpired(normalized)) {
+      if (idx >= 0) this.cookies.splice(idx, 1);
+      return;
+    }
+
+    if (idx >= 0) {
+      const previous = this.cookies[idx];
+      this.cookies[idx] = {
+        ...normalized,
+        creationIndex: previous?.creationIndex ?? normalized.creationIndex,
+      };
+    } else {
+      this.cookies.push(normalized);
+    }
+  }
+
+  setCookieFromHeader(setCookie: string, requestUrl: string): void {
+    const parsed = parseSetCookie(setCookie, requestUrl);
+    if (parsed) this.setCookie(parsed);
+  }
+
+  getCookieHeader(url: string): string | null {
+    const matching = this.matchingCookies(url).sort(cookieHeaderSort);
+    if (!matching.length) return null;
+    return matching.map((c) => `${c.name}=${c.value}`).join('; ');
+  }
+
+  lookup(
+    name: string,
+    requestUrl: string,
+    constraints: CookieLookupConstraints = {},
+  ): CookieLookupResult {
+    const url = constraints.url ?? requestUrl;
+    let matching = this.matchingCookies(url).filter((c) => c.name === name);
+    if (constraints.domain) {
+      const domain = normalizeDomain(constraints.domain);
+      matching = matching.filter((c) => normalizeDomain(c.domain) === domain);
+    }
+    if (constraints.path) matching = matching.filter((c) => c.path === constraints.path);
+    if (constraints.sameSite) {
+      matching = matching.filter(
+        (c) => (c.sameSite ?? '').toLowerCase() === constraints.sameSite?.toLowerCase(),
+      );
+    }
+
+    if (!matching.length) return { ok: false, reason: 'missing', matches: [] };
+    if (matching.length > 1) {
+      return { ok: false, reason: 'ambiguous', matches: matching.sort(cookieHeaderSort) };
+    }
+    const top = matching[0];
+    if (!top) return { ok: false, reason: 'missing', matches: [] };
+    if (top.httpOnly && constraints.allowHttpOnlyProjection !== true) {
+      return { ok: false, reason: 'httponly', matches: [top] };
+    }
+    return { ok: true, cookie: top };
+  }
+
+  private matchingCookies(url: string): RuntimeCookie[] {
+    let parsed: URL;
+    try {
+      parsed = new URL(url);
+    } catch {
+      return [];
+    }
+    const host = parsed.hostname.toLowerCase();
+    const path = parsed.pathname || '/';
+    const secure = parsed.protocol === 'https:';
+    const nowSeconds = Date.now() / 1000;
+
+    return this.cookies.filter((c) => {
+      if (c.expires !== undefined && c.expires <= nowSeconds) return false;
+      if (c.secure && !secure) return false;
+      if (!domainMatches(c, host)) return false;
+      return pathMatches(c.path, path);
+    });
+  }
+}
+
+export function extractSetCookieHeaders(headers: Headers): string[] {
+  const h = headers as Headers & { getSetCookie?: () => string[] };
+  if (typeof h.getSetCookie === 'function') return h.getSetCookie();
+  const sc = headers.get('set-cookie');
+  return sc ? splitSetCookieHeader(sc) : [];
+}
+
+/** Split a concatenated Set-Cookie header without splitting inside Expires. */
+export function splitSetCookieHeader(joined: string): string[] {
+  return joined.split(/,\s*(?=[A-Za-z0-9!#$%&'*+\-.^_`|~]+=)/);
+}
+
+function parseSetCookie(setCookie: string, requestUrl: string): RuntimeCookie | null {
+  const parts = setCookie.split(';').map((s) => s.trim());
+  const first = parts[0] ?? '';
+  const eq = first.indexOf('=');
+  if (eq <= 0) return null;
+
+  let url: URL;
+  try {
+    url = new URL(requestUrl);
+  } catch {
+    return null;
+  }
+
+  const cookie: RuntimeCookie = {
+    name: first.slice(0, eq),
+    value: first.slice(eq + 1),
+    domain: url.hostname,
+    path: defaultPath(url.pathname),
+    hostOnly: true,
+  };
+
+  for (const attr of parts.slice(1)) {
+    const attrEq = attr.indexOf('=');
+    const rawName = attrEq === -1 ? attr : attr.slice(0, attrEq);
+    const rawValue = attrEq === -1 ? '' : attr.slice(attrEq + 1);
+    const name = rawName.toLowerCase();
+
+    if (name === 'domain') {
+      cookie.domain = normalizeDomain(rawValue);
+      cookie.hostOnly = false;
+    } else if (name === 'path') {
+      cookie.path = rawValue.startsWith('/') ? rawValue : '/';
+    } else if (name === 'expires') {
+      const ms = Date.parse(rawValue);
+      if (!Number.isNaN(ms)) cookie.expires = Math.floor(ms / 1000);
+    } else if (name === 'max-age') {
+      const seconds = Number.parseInt(rawValue, 10);
+      if (Number.isFinite(seconds)) cookie.expires = Math.floor(Date.now() / 1000) + seconds;
+    } else if (name === 'httponly') {
+      cookie.httpOnly = true;
+    } else if (name === 'secure') {
+      cookie.secure = true;
+    } else if (name === 'samesite') {
+      cookie.sameSite = rawValue;
+    }
+  }
+
+  return normalizeCookie(cookie);
+}
+
+function normalizeCookie(cookie: RuntimeCookie): RuntimeCookie {
+  const expires = cookie.expires === -1 ? undefined : cookie.expires;
+  return {
+    ...cookie,
+    expires,
+    domain: normalizeDomain(cookie.domain),
+    path: cookie.path || '/',
+    hostOnly: cookie.hostOnly ?? !cookie.domain.startsWith('.'),
+    creationIndex: cookie.creationIndex ?? globalCreationIndex++,
+  };
+}
+
+function normalizeDomain(domain: string): string {
+  return domain.replace(/^\./, '').toLowerCase();
+}
+
+function isExpired(cookie: RuntimeCookie): boolean {
+  return cookie.expires !== undefined && cookie.expires <= Date.now() / 1000;
+}
+
+function domainMatches(cookie: RuntimeCookie, host: string): boolean {
+  const dom = normalizeDomain(cookie.domain);
+  return cookie.hostOnly ? host === dom : host === dom || host.endsWith(`.${dom}`);
+}
+
+function pathMatches(cookiePath: string, requestPath: string): boolean {
+  if (requestPath === cookiePath) return true;
+  if (!requestPath.startsWith(cookiePath)) return false;
+  return cookiePath.endsWith('/') || requestPath.charAt(cookiePath.length) === '/';
+}
+
+function defaultPath(pathname: string): string {
+  if (!pathname || pathname[0] !== '/') return '/';
+  if (pathname === '/') return '/';
+  const idx = pathname.lastIndexOf('/');
+  return idx <= 0 ? '/' : pathname.slice(0, idx);
+}
+
+function cookieHeaderSort(a: RuntimeCookie, b: RuntimeCookie): number {
+  return (
+    b.path.length - a.path.length ||
+    Number(b.hostOnly === true) - Number(a.hostOnly === true) ||
+    (a.creationIndex ?? 0) - (b.creationIndex ?? 0)
+  );
+}

package/src/imprint/credential-bundle.ts

@@ -0,0 +1,195 @@
+/**
+ * Encrypted credential bundle export/import.
+ *
+ * Use case: a user teaches a skill on their laptop and ships both the skill
+ * folder AND the credentials to a remote OpenClaw/Hermes agent. The skill
+ * folder lives in git (no plaintext), and credentials travel as a passphrase
+ * -encrypted bundle file the user can transport via any channel.
+ *
+ * Bundle wire format (JSON envelope; bytes never touch disk unencrypted):
+ * ```
+ * {
+ *   "version": 1,
+ *   "site": "<site>",
+ *   "createdAt": "<iso>",
+ *   "kdf": { "alg": "argon2id", "t": 3, "m": 65536, "p": 4, "saltB64": "..." },
+ *   "cipher": { "alg": "xsalsa20poly1305", "nonceB64": "...", "ctB64": "..." }
+ * }
+ * ```
+ * Plaintext (after decrypt) = `{ secrets: Record<string,string>, cookies: CookieRecord[], storage?: StorageRecord[], manifest: ManifestEntry[] }`.
+ */
+
+import { argon2id } from '@noble/hashes/argon2.js';
+import {
+  type CookieRecord,
+  type CredentialBackend,
+  type ManifestEntry,
+  type StorageRecord,
+  readSiteManifest,
+  writeSiteManifest,
+} from './credential-store.ts';
+
+interface BundlePlaintext {
+  secrets: Record<string, string>;
+  cookies: CookieRecord[];
+  storage?: StorageRecord[];
+  manifest: ManifestEntry[];
+}
+
+export interface BundleEnvelope {
+  version: 1;
+  site: string;
+  createdAt: string;
+  kdf: { alg: 'argon2id'; t: number; m: number; p: number; saltB64: string };
+  cipher: { alg: 'xsalsa20poly1305'; nonceB64: string; ctB64: string };
+}
+
+const KDF_T = 3;
+const KDF_M = 64 * 1024;
+const KDF_P = 4;
+
+function deriveKey(passphrase: string, salt: Uint8Array): Uint8Array {
+  return argon2id(new TextEncoder().encode(passphrase), salt, {
+    t: KDF_T,
+    m: KDF_M,
+    p: KDF_P,
+    dkLen: 32,
+  });
+}
+
+function b64encode(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('base64');
+}
+
+function b64decode(s: string): Uint8Array {
+  return new Uint8Array(Buffer.from(s, 'base64'));
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: lazy libsodium ref
+let sodiumPromise: Promise<any> | null = null;
+// biome-ignore lint/suspicious/noExplicitAny: lazy libsodium ref
+async function getSodium(): Promise<any> {
+  if (!sodiumPromise) {
+    sodiumPromise = import('libsodium-wrappers').then(async (m) => {
+      await m.default.ready;
+      return m.default;
+    });
+  }
+  return sodiumPromise;
+}
+
+export async function exportBundle(opts: {
+  backend: CredentialBackend;
+  site: string;
+  passphrase: string;
+}): Promise<BundleEnvelope> {
+  if (opts.passphrase.length < 8) {
+    throw new Error('Passphrase must be at least 8 characters.');
+  }
+  const sodium = await getSodium();
+
+  const names = await opts.backend.listSecrets(opts.site);
+  const secrets: Record<string, string> = {};
+  for (const n of names) {
+    const v = await opts.backend.getSecret(opts.site, n);
+    if (v !== null) secrets[n] = v;
+  }
+  const cookies = await opts.backend.getCookies(opts.site);
+  const storage = (await opts.backend.getStorage?.(opts.site)) ?? [];
+  const manifest = readSiteManifest(opts.site)?.secrets ?? [];
+
+  const plaintext: BundlePlaintext = { secrets, cookies, storage, manifest };
+  const text = new TextEncoder().encode(JSON.stringify(plaintext));
+
+  const salt = sodium.randombytes_buf(16);
+  const key = deriveKey(opts.passphrase, salt);
+  const nonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
+  const ct = sodium.crypto_secretbox_easy(text, nonce, key);
+
+  return {
+    version: 1,
+    site: opts.site,
+    createdAt: new Date().toISOString(),
+    kdf: { alg: 'argon2id', t: KDF_T, m: KDF_M, p: KDF_P, saltB64: b64encode(salt) },
+    cipher: { alg: 'xsalsa20poly1305', nonceB64: b64encode(nonce), ctB64: b64encode(ct) },
+  };
+}
+
+export async function decryptBundle(opts: {
+  envelope: BundleEnvelope;
+  passphrase: string;
+}): Promise<BundlePlaintext> {
+  const sodium = await getSodium();
+  if (opts.envelope.version !== 1) {
+    throw new Error(`Unknown bundle version ${opts.envelope.version}.`);
+  }
+  if (opts.envelope.kdf.alg !== 'argon2id') {
+    throw new Error(`Unsupported KDF "${opts.envelope.kdf.alg}".`);
+  }
+  if (opts.envelope.cipher.alg !== 'xsalsa20poly1305') {
+    throw new Error(`Unsupported cipher "${opts.envelope.cipher.alg}".`);
+  }
+
+  const salt = b64decode(opts.envelope.kdf.saltB64);
+  const nonce = b64decode(opts.envelope.cipher.nonceB64);
+  const ct = b64decode(opts.envelope.cipher.ctB64);
+  const key = argon2id(new TextEncoder().encode(opts.passphrase), salt, {
+    t: opts.envelope.kdf.t,
+    m: opts.envelope.kdf.m,
+    p: opts.envelope.kdf.p,
+    dkLen: 32,
+  });
+
+  let plain: Uint8Array;
+  try {
+    plain = sodium.crypto_secretbox_open_easy(ct, nonce, key);
+  } catch {
+    throw new Error('Wrong passphrase, or the bundle has been tampered with.');
+  }
+  return JSON.parse(new TextDecoder().decode(plain)) as BundlePlaintext;
+}
+
+export async function importBundle(opts: {
+  backend: CredentialBackend;
+  envelope: BundleEnvelope;
+  passphrase: string;
+  /** When true, abort if any secret already exists for this site. Default false (overwrite). */
+  failOnConflict?: boolean;
+}): Promise<{ imported: string[]; cookieCount: number; storageCount: number }> {
+  const data = await decryptBundle({ envelope: opts.envelope, passphrase: opts.passphrase });
+  const site = opts.envelope.site;
+
+  if (opts.failOnConflict) {
+    const existing = await opts.backend.listSecrets(site);
+    const conflicts = existing.filter((n) => n in data.secrets);
+    if (conflicts.length > 0) {
+      throw new Error(
+        `Refusing to overwrite existing secrets for "${site}": ${conflicts.join(', ')}\n→ delete them first or rerun without --fail-on-conflict.`,
+      );
+    }
+  }
+
+  const imported: string[] = [];
+  for (const [name, value] of Object.entries(data.secrets)) {
+    await opts.backend.setSecret(site, name, value);
+    imported.push(name);
+  }
+
+  if (data.cookies.length > 0) {
+    await opts.backend.setCookies(site, data.cookies);
+  }
+
+  if (data.storage && data.storage.length > 0 && opts.backend.setStorage) {
+    await opts.backend.setStorage(site, data.storage);
+  }
+
+  if (data.manifest.length > 0) {
+    writeSiteManifest({
+      site,
+      secrets: data.manifest,
+      updatedAt: new Date().toISOString(),
+    });
+  }
+
+  return { imported, cookieCount: data.cookies.length, storageCount: data.storage?.length ?? 0 };
+}