@k2b/cloud 0.6.0-rc.0

package/src/browser/app-approval-vault.ts

@@ -0,0 +1,305 @@
+import { z } from "zod";
+import { AppDevicePublicKeySchema } from "../contracts/app-approval";
+import type { AppApprovalKey } from "./app-approval";
+
+const keyGuards = new WeakMap<CryptoKey, () => void>();
+export function assertVaultKey(key: CryptoKey) {
+  keyGuards.get(key)?.();
+}
+const bytes = (length: number) => crypto.getRandomValues(new Uint8Array(length));
+const encode = (value: Uint8Array<ArrayBuffer>) => btoa(String.fromCharCode(...value));
+const decode = (value: string) => Uint8Array.from(atob(value), (c) => c.charCodeAt(0));
+const text = new TextEncoder();
+const base64 = (length: number) =>
+  z
+    .string()
+    .max(length * 2)
+    .refine((s) => {
+      try {
+        return decode(s).length === length && encode(decode(s)) === s;
+      } catch {
+        return false;
+      }
+    });
+const blobSchema = z.object({ iv: base64(12), data: z.string().max(2_000_000) }).strict();
+const pinSchema = z
+  .object({ type: z.literal("pin"), salt: base64(16), kdf: z.literal("argon2id-64m-t3-p1"), wrapped: blobSchema })
+  .strict();
+const passkeySchema = z
+  .object({ type: z.literal("passkey"), credentialId: z.string().min(1).max(2048), salt: base64(32), wrapped: blobSchema })
+  .strict();
+const methodSchema = z.discriminatedUnion("type", [pinSchema, passkeySchema]);
+const configSchema = z
+  .object({ version: z.literal(1), id: base64(16), methods: z.array(methodSchema).min(1).max(2) })
+  .strict()
+  .refine((c) => new Set(c.methods.map((m) => m.type)).size === c.methods.length);
+export type AppVaultConfig = z.infer<typeof configSchema>;
+export type AppVaultBlob = z.infer<typeof blobSchema>;
+export type AppVaultMethod = AppVaultConfig["methods"][number];
+export type AppVaultSession = ReturnType<typeof session>;
+export class AppVaultError extends Error {
+  constructor(public readonly code: "LOCKED" | "INVALID" | "UNSUPPORTED") {
+    super(`App vault: ${code}`);
+  }
+}
+const invalid = () => new AppVaultError("INVALID");
+const aes = (raw: Uint8Array<ArrayBuffer>) => crypto.subtle.importKey("raw", raw, "AES-GCM", false, ["encrypt", "decrypt"]);
+async function encrypt(key: CryptoKey, data: Uint8Array<ArrayBuffer>, context: string): Promise<AppVaultBlob> {
+  const iv = bytes(12);
+  return {
+    iv: encode(iv),
+    data: encode(
+      new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv, additionalData: text.encode(context), tagLength: 128 }, key, data)),
+    ),
+  };
+}
+async function decrypt(key: CryptoKey, value: AppVaultBlob, context: string) {
+  const b = blobSchema.parse(value);
+  try {
+    return new Uint8Array(
+      await crypto.subtle.decrypt(
+        { name: "AES-GCM", iv: decode(b.iv), additionalData: text.encode(context), tagLength: 128 },
+        key,
+        decode(b.data),
+      ),
+    );
+  } catch {
+    throw invalid();
+  }
+}
+async function pinKey(pin: string, salt: string) {
+  if (!/^[0-9]{6}$/.test(pin)) throw invalid();
+  const { argon2id } = await import("hash-wasm");
+  // Based on RFC 9106's memory-constrained profile: 64 MiB, three passes; one browser lane.
+  const raw = await argon2id({
+    password: pin,
+    salt: decode(salt),
+    parallelism: 1,
+    iterations: 3,
+    memorySize: 65536,
+    hashLength: 32,
+    outputType: "binary",
+  });
+  try {
+    return await aes(new Uint8Array(raw));
+  } finally {
+    raw.fill(0);
+  }
+}
+function wrapContext(id: string, method: Omit<z.infer<typeof pinSchema>, "wrapped"> | Omit<z.infer<typeof passkeySchema>, "wrapped">) {
+  return JSON.stringify(["cloud-login-vault", 1, id, method.type, method.salt, method.type === "pin" ? method.kdf : method.credentialId]);
+}
+function methodContext(id: string, method: AppVaultMethod) {
+  return wrapContext(
+    id,
+    method.type === "pin"
+      ? { type: "pin", salt: method.salt, kdf: method.kdf }
+      : { type: "passkey", salt: method.salt, credentialId: method.credentialId },
+  );
+}
+function extension(credential: Credential | null): { id: string; enabled: boolean; output?: Uint8Array<ArrayBuffer> } {
+  if (!(credential instanceof PublicKeyCredential)) throw invalid();
+  const result: unknown = credential.getClientExtensionResults();
+  const parsed = z
+    .object({
+      prf: z.object({ enabled: z.boolean().optional(), results: z.object({ first: z.instanceof(ArrayBuffer) }).optional() }).optional(),
+    })
+    .parse(result);
+  const first = parsed.prf?.results?.first;
+  if (first && first.byteLength !== 32) throw invalid();
+  return {
+    id: encode(new Uint8Array(credential.rawId)),
+    enabled: parsed.prf?.enabled === true,
+    output: first ? new Uint8Array(first) : undefined,
+  };
+}
+async function passkeyKey(credentialId: string, salt: string, signal?: AbortSignal) {
+  const credential = await navigator.credentials.get({
+    publicKey: {
+      challenge: bytes(32),
+      rpId: location.hostname,
+      allowCredentials: [{ type: "public-key", id: decode(credentialId) }],
+      userVerification: "required",
+      extensions: { prf: { eval: { first: decode(salt) } } },
+    },
+    signal,
+  });
+  const result = extension(credential);
+  if (result.id !== credentialId || !result.output) throw new AppVaultError("UNSUPPORTED");
+  return derivePasskeyKey(result.output);
+}
+async function derivePasskeyKey(output: Uint8Array<ArrayBuffer>) {
+  try {
+    const ikm = await crypto.subtle.importKey("raw", output, "HKDF", false, ["deriveKey"]);
+    return await crypto.subtle.deriveKey(
+      { name: "HKDF", hash: "SHA-256", salt: text.encode(location.origin), info: text.encode("cloud-login-vault-wrap-v1") },
+      ikm,
+      { name: "AES-GCM", length: 256 },
+      false,
+      ["encrypt", "decrypt"],
+    );
+  } finally {
+    output.fill(0);
+  }
+}
+async function capability(): Promise<"supported" | "unknown" | "unsupported"> {
+  if (
+    !globalThis.isSecureContext ||
+    !globalThis.PublicKeyCredential ||
+    !navigator.credentials ||
+    /^(?:[0-9]+\.){3}[0-9]+$|^\[/.test(location.hostname)
+  )
+    return "unsupported";
+  if (!PublicKeyCredential.getClientCapabilities) return "unknown";
+  try {
+    const caps = await PublicKeyCredential.getClientCapabilities();
+    const prf = caps["extension:prf"];
+    return prf === true ? "supported" : prf === false ? "unsupported" : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+function session(id: string, raw: Uint8Array<ArrayBuffer>, key: CryptoKey) {
+  let live = true;
+  const imported = new Map<string, AppApprovalKey>();
+  const materials = new Map<CryptoKey, Uint8Array<ArrayBuffer>>();
+  const check = () => {
+    if (!live) throw new AppVaultError("LOCKED");
+  };
+  const importPrivate = async (material: Uint8Array<ArrayBuffer>, publicKey: AppApprovalKey["publicKey"]): Promise<AppApprovalKey> => {
+    check();
+    const cacheId = encode(material);
+    const cached = imported.get(cacheId);
+    if (cached && JSON.stringify(cached.publicKey) === JSON.stringify(publicKey)) return cached;
+    const privateKey = await crypto.subtle.importKey("pkcs8", material, { name: "ECDSA", namedCurve: "P-256" }, false, ["sign"]);
+    const pub = await crypto.subtle.importKey("jwk", publicKey, { name: "ECDSA", namedCurve: "P-256" }, false, ["verify"]);
+    const challenge = bytes(32);
+    const proof = await crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, privateKey, challenge);
+    if (!(await crypto.subtle.verify({ name: "ECDSA", hash: "SHA-256" }, pub, proof, challenge))) throw invalid();
+    check();
+    materials.set(privateKey, material.slice());
+    keyGuards.set(privateKey, check);
+    const value = { privateKey, publicKey };
+    imported.set(cacheId, value);
+    return value;
+  };
+  return {
+    id,
+    check,
+    lock() {
+      live = false;
+      raw.fill(0);
+      for (const material of materials.values()) material.fill(0);
+      materials.clear();
+      imported.clear();
+    },
+    async createKey() {
+      check();
+      const pair = await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]);
+      const jwk = await crypto.subtle.exportKey("jwk", pair.publicKey);
+      const publicKey = AppDevicePublicKeySchema.parse({ kty: jwk.kty, crv: jwk.crv, x: jwk.x, y: jwk.y });
+      const material = new Uint8Array(await crypto.subtle.exportKey("pkcs8", pair.privateKey));
+      try {
+        return await importPrivate(material, publicKey);
+      } finally {
+        material.fill(0);
+      }
+    },
+    async sealRecord<T extends { key: AppApprovalKey }>(record: T, context: string) {
+      check();
+      const material = materials.get(record.key.privateKey);
+      if (!material) throw invalid();
+      const plain = text.encode(JSON.stringify({ ...record, key: { privateKey: encode(material), publicKey: record.key.publicKey } }));
+      try {
+        const blob = await encrypt(key, plain, JSON.stringify(["cloud-login-record", 1, id, context]));
+        check();
+        return blob;
+      } finally {
+        plain.fill(0);
+      }
+    },
+    async openRecord<T>(blob: AppVaultBlob, context: string, validate: (value: unknown) => T): Promise<T> {
+      check();
+      const plain = await decrypt(key, blob, JSON.stringify(["cloud-login-record", 1, id, context]));
+      try {
+        const parsed = z
+          .object({ key: z.object({ privateKey: z.string().max(512), publicKey: AppDevicePublicKeySchema }).strict() })
+          .passthrough()
+          .parse(JSON.parse(new TextDecoder().decode(plain)));
+        const material = decode(parsed.key.privateKey);
+        try {
+          const result = validate({ ...parsed, key: await importPrivate(material, parsed.key.publicKey) });
+          check();
+          return result;
+        } finally {
+          material.fill(0);
+        }
+      } finally {
+        plain.fill(0);
+      }
+    },
+    async pin(pin: string): Promise<AppVaultMethod> {
+      check();
+      const method = { type: "pin" as const, salt: encode(bytes(16)), kdf: "argon2id-64m-t3-p1" as const };
+      const wrapping = await pinKey(pin, method.salt);
+      check();
+      const wrapped = await encrypt(wrapping, raw, wrapContext(id, method));
+      check();
+      return { ...method, wrapped };
+    },
+    async passkey(signal?: AbortSignal): Promise<AppVaultMethod> {
+      check();
+      const salt = encode(bytes(32));
+      const credential = await navigator.credentials.create({
+        publicKey: {
+          challenge: bytes(32),
+          rp: { id: location.hostname, name: "Cloud Login" },
+          user: { id: bytes(32), name: "Cloud Login", displayName: "Cloud Login" },
+          pubKeyCredParams: [{ type: "public-key", alg: -7 }],
+          authenticatorSelection: { residentKey: "required", userVerification: "required" },
+          attestation: "none",
+          extensions: { prf: { eval: { first: decode(salt) } } },
+        },
+        signal,
+      });
+      const result = extension(credential);
+      if (!result.enabled) {
+        result.output?.fill(0);
+        throw new AppVaultError("UNSUPPORTED");
+      }
+      const method = { type: "passkey" as const, credentialId: result.id, salt };
+      // Some providers evaluate PRF during creation; others require authentication.
+      const wrapping = result.output ? await derivePasskeyKey(result.output) : await passkeyKey(method.credentialId, method.salt, signal);
+      check();
+      const wrapped = await encrypt(wrapping, raw, wrapContext(id, method));
+      check();
+      return { ...method, wrapped };
+    },
+  };
+}
+async function create() {
+  const raw = bytes(32);
+  return session(encode(bytes(16)), raw, await aes(raw));
+}
+async function unlock(config: AppVaultConfig, type: "pin" | "passkey", pin?: string, signal?: AbortSignal) {
+  const value = configSchema.parse(config);
+  const method = value.methods.find((m) => m.type === type);
+  if (!method) throw invalid();
+  const wrapping =
+    method.type === "pin" ? await pinKey(pin ?? "", method.salt) : await passkeyKey(method.credentialId, method.salt, signal);
+  const raw = await decrypt(wrapping, method.wrapped, methodContext(value.id, method));
+  if (raw.length !== 32) {
+    raw.fill(0);
+    throw invalid();
+  }
+  try {
+    signal?.throwIfAborted();
+    const key = await aes(raw);
+    signal?.throwIfAborted();
+    return session(value.id, raw, key);
+  } catch (error) {
+    raw.fill(0);
+    throw error;
+  }
+}
+export const appApprovalVault = { create, unlock, capability, parseConfig: (value: unknown) => configSchema.parse(value) };

package/src/browser/app-approval.ts

@@ -0,0 +1,234 @@
+import { appApprovalVault, assertVaultKey } from "./app-approval-vault";
+
+export { type AppVaultBlob, type AppVaultConfig, AppVaultError, type AppVaultMethod, type AppVaultSession } from "./app-approval-vault";
+
+import { z } from "zod";
+import {
+  APP_APPROVAL_LIMITS,
+  APP_APPROVAL_PATH,
+  APP_APPROVAL_PROTOCOL,
+  AppDeviceCommandSchema,
+  AppDeviceProofSchema,
+  type AppDevicePublicKey,
+  AppDevicePublicKeySchema,
+  AppDeviceResponseSchema,
+  AppPairingClaimResultSchema,
+  AppPairingClaimSchema,
+  type AppPairingPayload,
+  AppPairingPayloadSchema,
+  AppPairingResultSchema,
+  type AppPendingLogin,
+  AppPendingLoginSchema,
+  appDeviceProofMessage,
+  appPairingLink,
+  appPairingProofMessage,
+  parseAppPairingLink,
+} from "../contracts/app-approval";
+
+export interface AppApprovalKey {
+  privateKey: CryptoKey;
+  publicKey: AppDevicePublicKey;
+}
+export interface AppApprovalDevice {
+  issuer: string;
+  deviceId: string;
+  key: AppApprovalKey;
+}
+
+/** No remote error body or credential material is retained in an error. */
+export class AppApprovalClientError extends Error {
+  constructor(
+    public readonly code: "HTTP" | "INVALID_RESPONSE" | "NETWORK" | "INVALID_INPUT",
+    public readonly status?: number,
+  ) {
+    super(`App approval: ${code}`);
+  }
+}
+
+const origin = (input: string): string => {
+  const url = new URL(input);
+  if (
+    url.origin !== input ||
+    url.username ||
+    url.password ||
+    (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))
+  ) {
+    throw new AppApprovalClientError("INVALID_INPUT");
+  }
+  return url.origin;
+};
+
+const createKey = async (): Promise<AppApprovalKey> => {
+  const keys = await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, false, ["sign", "verify"]);
+  const jwk = await crypto.subtle.exportKey("jwk", keys.publicKey);
+  return { privateKey: keys.privateKey, publicKey: AppDevicePublicKeySchema.parse({ kty: jwk.kty, crv: jwk.crv, x: jwk.x, y: jwk.y }) };
+};
+
+const sign = async (key: AppApprovalKey, message: string) => {
+  assertVaultKey(key.privateKey);
+  if (key.privateKey.extractable || key.privateKey.type !== "private") throw new AppApprovalClientError("INVALID_INPUT");
+  const signature = new Uint8Array(
+    await crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, key.privateKey, new TextEncoder().encode(message)),
+  );
+  assertVaultKey(key.privateKey);
+  return btoa(String.fromCharCode(...signature))
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replaceAll("=", "");
+};
+
+const InfoSchema = z.object({
+  protocol: z.literal(APP_APPROVAL_PROTOCOL),
+  issuer: z.string(),
+  api: z.string(),
+  appOrigin: z.string(),
+  algorithm: z.literal("ES256"),
+  limits: z.object(Object.fromEntries(Object.entries(APP_APPROVAL_LIMITS).map(([key, value]) => [key, z.literal(value)]))),
+});
+
+/** Call only after the user explicitly trusts the issuer from a pairing link.
+ * Connect validates discovery before returning a client. */
+const connect = async (options: {
+  issuer: string;
+  authenticatorOrigin: string;
+  signal?: AbortSignal;
+  fetch?: (url: string, init: RequestInit) => Promise<Response>;
+}) => {
+  const issuer = origin(options.issuer);
+  const appOrigin = origin(options.authenticatorOrigin);
+  const fetcher = options.fetch ?? globalThis.fetch;
+  const request = async <T>(path: string, schema: z.ZodType<T>, body?: unknown, signal?: AbortSignal): Promise<T> => {
+    const serialized = body === undefined ? undefined : JSON.stringify(body);
+    if (serialized && new TextEncoder().encode(serialized).length > APP_APPROVAL_LIMITS.bodyBytes)
+      throw new AppApprovalClientError("INVALID_INPUT");
+    let response: Response;
+    const timeout = AbortSignal.timeout(APP_APPROVAL_LIMITS.proofSeconds * 1000);
+    const requestSignal = signal ? AbortSignal.any([signal, timeout]) : timeout;
+    try {
+      response = await fetcher(`${issuer}${APP_APPROVAL_PATH}${path}`, {
+        method: serialized === undefined ? "GET" : "POST",
+        body: serialized,
+        headers: serialized === undefined ? undefined : { "Content-Type": "application/json" },
+        credentials: "omit",
+        redirect: "error",
+        cache: "no-store",
+        referrerPolicy: "no-referrer",
+        signal: requestSignal,
+      });
+    } catch {
+      signal?.throwIfAborted();
+      throw new AppApprovalClientError("NETWORK");
+    }
+    if (!response.ok) {
+      await response.body?.cancel();
+      throw new AppApprovalClientError("HTTP", response.status);
+    }
+    // The response budget matches the bounded v1 request/pending-list budget.
+    const reader = response.body?.getReader();
+    if (!reader) throw new AppApprovalClientError("INVALID_RESPONSE");
+    const decoder = new TextDecoder();
+    let text = "",
+      bytes = 0;
+    try {
+      while (true) {
+        const chunk = await reader.read();
+        if (chunk.done) break;
+        bytes += chunk.value.length;
+        if (bytes > APP_APPROVAL_LIMITS.bodyBytes) {
+          await reader.cancel();
+          throw new AppApprovalClientError("INVALID_RESPONSE");
+        }
+        text += decoder.decode(chunk.value, { stream: true });
+      }
+      text += decoder.decode();
+      return schema.parse(JSON.parse(text));
+    } catch {
+      signal?.throwIfAborted();
+      throw new AppApprovalClientError("INVALID_RESPONSE");
+    } finally {
+      reader.releaseLock();
+    }
+  };
+  const info = await request("/info", InfoSchema, undefined, options.signal);
+  if (info.issuer !== issuer || info.appOrigin !== appOrigin || info.api !== `${issuer}${APP_APPROVAL_PATH}`)
+    throw new AppApprovalClientError("INVALID_RESPONSE");
+
+  const pairing = (payload: AppPairingPayload) => {
+    const parsed = AppPairingPayloadSchema.parse(payload);
+    if (parsed.issuer !== issuer || Date.parse(parsed.expiresAt) <= Date.now()) throw new AppApprovalClientError("INVALID_INPUT");
+    return parsed;
+  };
+  const command = async (device: AppApprovalDevice, input: z.infer<typeof AppDeviceCommandSchema>, signal?: AbortSignal) => {
+    if (device.issuer !== issuer) throw new AppApprovalClientError("INVALID_INPUT");
+    const now = Math.floor(Date.now() / 1000);
+    const proof = AppDeviceProofSchema.parse({
+      issuer,
+      deviceId: device.deviceId,
+      jti: crypto.randomUUID(),
+      issuedAt: now,
+      expiresAt: now + APP_APPROVAL_LIMITS.proofSeconds,
+      command: AppDeviceCommandSchema.parse(input),
+    });
+    return request("/device", AppDeviceResponseSchema, { proof, signature: await sign(device.key, appDeviceProofMessage(proof)) }, signal);
+  };
+  return {
+    issuer,
+    info,
+    claim: async (payload: AppPairingPayload, key: AppApprovalKey, name: string, signal?: AbortSignal) => {
+      const p = pairing(payload);
+      const input = AppPairingClaimSchema.omit({ signature: true }).parse({
+        pairingId: p.pairingId,
+        secret: p.secret,
+        publicKey: key.publicKey,
+        name,
+      });
+      return request(
+        "/pairings/claim",
+        AppPairingClaimResultSchema,
+        { ...input, signature: await sign(key, appPairingProofMessage(issuer, input)) },
+        signal,
+      );
+    },
+    pairingResult: (payload: AppPairingPayload, key: AppApprovalKey, signal?: AbortSignal) => {
+      const p = pairing(payload);
+      return request(
+        "/pairings/result",
+        AppPairingResultSchema,
+        { pairingId: p.pairingId, secret: p.secret, publicKey: AppDevicePublicKeySchema.parse(key.publicKey) },
+        signal,
+      );
+    },
+    pending: async (device: AppApprovalDevice, signal?: AbortSignal) => {
+      const result = await command(device, { operation: "pending" }, signal);
+      if (!("requests" in result)) throw new AppApprovalClientError("INVALID_RESPONSE");
+      return result;
+    },
+    decide: async (device: AppApprovalDevice, login: AppPendingLogin, decision: "approve" | "deny", signal?: AbortSignal) => {
+      login = AppPendingLoginSchema.parse(login);
+      if (Date.parse(login.expiresAt) <= Date.now()) throw new AppApprovalClientError("INVALID_INPUT");
+      const result = await command(
+        device,
+        { operation: "decide", requestId: login.requestId, challenge: login.challenge, comparison: login.comparison, decision },
+        signal,
+      );
+      if (!("state" in result) || result.state !== (decision === "approve" ? "approved" : "denied"))
+        throw new AppApprovalClientError("INVALID_RESPONSE");
+      return result;
+    },
+    revoke: async (device: AppApprovalDevice, signal?: AbortSignal) => {
+      const result = await command(device, { operation: "revoke" }, signal);
+      if (!("state" in result) || result.state !== "revoked") throw new AppApprovalClientError("INVALID_RESPONSE");
+      return result;
+    },
+  };
+};
+
+/** Browser-only SDK. Never polls, approves, retries mutations, or reads clipboard automatically. */
+export const appApproval = {
+  vault: appApprovalVault,
+  createPairingLink: appPairingLink,
+  parsePairingLink: parseAppPairingLink,
+  createKey,
+  connect,
+  limits: APP_APPROVAL_LIMITS,
+};