@ccmsg/cli 0.1.0 → 0.2.0

package/src/auth/cbor.ts

@@ -0,0 +1,150 @@
+/** Just enough CBOR to read what an authenticator hands over (DR-0001 §2.10).
+ *
+ * Two values arrive in this encoding and no others: the attestation object,
+ * which is a map of three entries, and the COSE public key inside it, which is
+ * a map keyed by small integers. So the decoder covers the five major types
+ * those use — unsigned and negative integers, byte and text strings, arrays and
+ * maps — and refuses everything else rather than growing toward a general
+ * implementation nothing here would call.
+ *
+ * Indefinite lengths are refused for the same reason: WebAuthn requires
+ * canonical CTAP2 encoding, where every length is definite, so accepting one
+ * would be accepting something no conforming authenticator produces.
+ *
+ * Nesting is bounded because the input is attacker-supplied: a value that is
+ * nothing but a few thousand nested arrays costs one byte each to write and a
+ * stack frame each to read, and this decoder runs on a route reachable before
+ * anything is proven. */
+
+export class CborError extends Error {}
+
+/** How deep a value may nest. The two shapes this reads are a map of three
+ * entries holding a map of five, so anything past a handful is not one of
+ * them. */
+const MAX_DEPTH = 8;
+
+/** One decoded value, and where the next one starts. */
+interface Read<T> {
+  readonly value: T;
+  readonly next: number;
+}
+
+export type CborValue =
+  | number
+  | string
+  | Uint8Array
+  | CborValue[]
+  | Map<number | string, CborValue>
+  | boolean
+  | null;
+
+/** Decode one value, and say how many bytes were left after it.
+ *
+ * The remainder is answered rather than ignored because trailing bytes mean
+ * the value was not what the encoder said it was, and the caller — which knows
+ * whether its input is exactly one value — is where that is worth refusing. */
+export function decodeCbor(bytes: Uint8Array): { value: CborValue; rest: number } {
+  const read = value(bytes, 0, 0);
+  return { value: read.value, rest: bytes.length - read.next };
+}
+
+/** Decode one value that is the whole of the input. */
+export function decodeCborWhole(bytes: Uint8Array): CborValue {
+  const { value: decoded, rest } = decodeCbor(bytes);
+  if (rest !== 0) throw new CborError(`${String(rest)} bytes follow the value`);
+  return decoded;
+}
+
+function value(bytes: Uint8Array, at: number, depth: number): Read<CborValue> {
+  if (depth > MAX_DEPTH) throw new CborError("this value nests too deeply to be read here");
+  const initial = byte(bytes, at);
+  const major = initial >> 5;
+  const minor = initial & 0x1f;
+  switch (major) {
+    case 0: {
+      const read = argument(bytes, at + 1, minor);
+      return { value: read.value, next: read.next };
+    }
+    case 1: {
+      const read = argument(bytes, at + 1, minor);
+      return { value: -1 - read.value, next: read.next };
+    }
+    case 2: {
+      const read = argument(bytes, at + 1, minor);
+      const end = read.next + read.value;
+      if (end > bytes.length) throw new CborError("a byte string runs past the end");
+      return { value: bytes.subarray(read.next, end), next: end };
+    }
+    case 3: {
+      const read = argument(bytes, at + 1, minor);
+      const end = read.next + read.value;
+      if (end > bytes.length) throw new CborError("a text string runs past the end");
+      return { value: new TextDecoder().decode(bytes.subarray(read.next, end)), next: end };
+    }
+    case 4: {
+      const read = argument(bytes, at + 1, minor);
+      const items: CborValue[] = [];
+      let cursor = read.next;
+      for (let i = 0; i < read.value; i += 1) {
+        const item = value(bytes, cursor, depth + 1);
+        items.push(item.value);
+        cursor = item.next;
+      }
+      return { value: items, next: cursor };
+    }
+    case 5: {
+      const read = argument(bytes, at + 1, minor);
+      const entries = new Map<number | string, CborValue>();
+      let cursor = read.next;
+      for (let i = 0; i < read.value; i += 1) {
+        const key = value(bytes, cursor, depth + 1);
+        if (typeof key.value !== "number" && typeof key.value !== "string") {
+          throw new CborError("a map key here is an integer or a string");
+        }
+        const held = value(bytes, key.next, depth + 1);
+        entries.set(key.value, held.value);
+        cursor = held.next;
+      }
+      return { value: entries, next: cursor };
+    }
+    case 7: {
+      // The three simple values that appear in an attestation statement.
+      if (minor === 20) return { value: false, next: at + 1 };
+      if (minor === 21) return { value: true, next: at + 1 };
+      if (minor === 22) return { value: null, next: at + 1 };
+      throw new CborError(`simple value ${String(minor)} is not read here`);
+    }
+    default:
+      throw new CborError(`major type ${String(major)} is not read here`);
+  }
+}
+
+/** The count, length or value an initial byte's low bits introduce. */
+function argument(bytes: Uint8Array, at: number, minor: number): Read<number> {
+  if (minor < 24) return { value: minor, next: at };
+  if (minor === 24) return { value: byte(bytes, at), next: at + 1 };
+  if (minor === 25) return { value: (byte(bytes, at) << 8) | byte(bytes, at + 1), next: at + 2 };
+  if (minor === 26) {
+    const held =
+      byte(bytes, at) * 0x1000000 +
+      (byte(bytes, at + 1) << 16) +
+      (byte(bytes, at + 2) << 8) +
+      byte(bytes, at + 3);
+    return { value: held, next: at + 4 };
+  }
+  // 27 is a 64-bit argument and 31 is an indefinite length. Neither appears in
+  // what an authenticator sends, and a length past 2^32 is not something this
+  // process would then go on to allocate.
+  throw new CborError(`length form ${String(minor)} is not read here`);
+}
+
+function byte(bytes: Uint8Array, at: number): number {
+  const held = bytes[at];
+  if (held === undefined) throw new CborError("the value runs past the end");
+  return held;
+}
+
+/** One entry of a decoded map, refusing when the value is not what was wanted. */
+export function mapEntry(value: CborValue, key: number | string): CborValue | undefined {
+  return value instanceof Map ? value.get(key) : undefined;
+}

package/src/auth/http.ts

@@ -0,0 +1,280 @@
+import { createHash } from "node:crypto";
+import {
+  type AuthAssertArgs,
+  type AuthRegisterArgs,
+  type ErrorCode,
+  type InstanceId,
+  OP_SCHEMAS,
+  type OpName,
+  validationErrors,
+} from "@ccmsg/protocol";
+import { OpError } from "../dispatch/index.ts";
+import type { Auth, MintedSession } from "./auth.ts";
+
+/** The four ops the contract carries over HTTP, and the path each is at.
+ *
+ * They are `needs_hello: false` ops like `hello` is, run before there is an
+ * identity to check, and the carrier is what makes them reachable from a page
+ * that has no connection yet — a `request_id` is synthesized here because
+ * there is no envelope to carry one (DR-0001 §2.9). */
+const ROUTES = ["challenge", "register", "assert", "refresh"] as const;
+type Route = (typeof ROUTES)[number];
+
+/** Which op each route carries. The route is a name a proxy can see; the op is
+ * what the attribute table and the schemas are keyed by. */
+const OP_OF: Record<Route, OpName> = {
+  challenge: "auth_challenge",
+  register: "auth_register",
+  assert: "auth_assert",
+  refresh: "auth_refresh_token",
+};
+
+/** Cap on an `/auth/*` body. Everything these take is a handful of base64url
+ * fields; an attestation object is a few hundred bytes. */
+const MAX_BODY_BYTES = 64 * 1024;
+
+/** Which of the routes a path is, matched at the end rather than whole.
+ *
+ * The prefix is not read, for the reason the WebSocket's own entry is not:
+ * a proxy may put the instance under a prefix of its own, and which instance
+ * was meant is settled by the address it forwarded to (DR-0001 §2.7). */
+export function authRouteOf(pathname: string): Route | undefined {
+  const marker = "/auth/";
+  const at = pathname.lastIndexOf(marker);
+  if (at === -1) return undefined;
+  const name = pathname.slice(at + marker.length);
+  return (ROUTES as readonly string[]).includes(name) ? (name as Route) : undefined;
+}
+
+/** The cookie path for a request: everything up to and including its `/auth/`.
+ *
+ * It narrows what the browser sends where, and nothing more — same-origin
+ * script can fetch any path, so this is not an authorization boundary (§2.4).
+ * What it is for is that two endpoints behind one origin (`/` and `/personal`)
+ * get cookies of their own. */
+export function cookiePath(pathname: string): string {
+  const at = pathname.lastIndexOf("/auth/");
+  return at === -1 ? "/" : pathname.slice(0, at + "/auth/".length);
+}
+
+/** What a person's refresh cookie is called on this instance.
+ *
+ * Named after the instance and the subject so that two instances behind one
+ * origin, and two people at one browser, do not overwrite each other's. The
+ * digest is what keeps the id and the subject out of a header a page can
+ * read. */
+export function cookieName(instance: InstanceId, sub: string): string {
+  const digest = createHash("sha256").update(`${instance}\n${sub}`).digest("hex").slice(0, 16);
+  return `__Secure-ccmsg-${digest}`;
+}
+
+/** The value of one cookie in a request, or nothing. */
+export function cookieValue(header: string | null, name: string): string | undefined {
+  if (header === null) return undefined;
+  for (const part of header.split(";")) {
+    const at = part.indexOf("=");
+    if (at === -1) continue;
+    if (part.slice(0, at).trim() !== name) continue;
+    return part.slice(at + 1).trim();
+  }
+  return undefined;
+}
+
+export interface AuthRoutesDeps {
+  readonly auth: Auth;
+  readonly self: InstanceId;
+  readonly origins: () => readonly string[];
+  readonly log?: (msg: string, fields?: Record<string, unknown>) => void;
+}
+
+/** Serve `/auth/*`, or answer nothing when the request is for something else.
+ *
+ * Everything unauthenticated shares one rate limit and one origin check: these
+ * routes are reachable before anything is proven, and the work behind them is a
+ * signature verification (§2.4). */
+export async function handleAuth(
+  request: Request,
+  deps: AuthRoutesDeps,
+  from: { ip?: string } = {},
+): Promise<Response | undefined> {
+  const url = new URL(request.url);
+  const route = authRouteOf(url.pathname);
+  if (route === undefined) return undefined;
+  const origin = request.headers.get("origin");
+  const allowed = deps.origins();
+  // A page from an origin this instance does not serve is refused before
+  // anything else, including the preflight that would tell it to try.
+  if (origin !== null && !allowed.includes(origin)) {
+    return new Response("Forbidden", { status: 403 });
+  }
+  // These routes change state and are reachable before anything is proven, so
+  // an `Origin` is required rather than merely compared (DR-0001 §2.4): a
+  // request carrying none is not a page this instance serves, and admitting it
+  // would leave the comparison above optional to whoever is making the call.
+  if (origin === null && request.method !== "OPTIONS") {
+    return new Response("Forbidden", { status: 403 });
+  }
+  const cors: Record<string, string> =
+    origin === null
+      ? {}
+      : {
+          "access-control-allow-origin": origin,
+          "access-control-allow-credentials": "true",
+          vary: "Origin",
+        };
+  if (request.method === "OPTIONS") {
+    return new Response(null, {
+      status: 204,
+      headers: {
+        ...cors,
+        "access-control-allow-methods": "POST, OPTIONS",
+        "access-control-allow-headers": "content-type",
+        "access-control-max-age": "600",
+      },
+    });
+  }
+  if (request.method !== "POST") {
+    return new Response("Method Not Allowed", { status: 405, headers: cors });
+  }
+  if (!deps.auth.allowRequest()) {
+    return new Response("too many requests", { status: 429, headers: cors });
+  }
+
+  let args: Record<string, unknown>;
+  try {
+    args = await body(request);
+  } catch (cause) {
+    return refusal("bad_request", String(cause), cors);
+  }
+  // The op's own schema, run before anything reads a field. The carrier
+  // synthesizes the envelope the contract asks for — there is no connection to
+  // carry one — so what is validated is the same frame dispatch would have
+  // validated, and a body missing a field is a refusal rather than a fault
+  // inside a handler.
+  const op = OP_OF[route];
+  // The body first, so a caller cannot name the op or the correlation id by
+  // putting either in it: what the carrier decided is what stands.
+  const frame = { ...args, op, request_id: `http-${crypto.randomUUID()}` };
+  const problems = validationErrors(OP_SCHEMAS[op].request, frame);
+  if (problems.length > 0) return refusal("invalid_args", problems.join("; "), cors);
+
+  const userAgent = request.headers.get("user-agent") ?? undefined;
+  const seen = {
+    ...(from.ip === undefined ? {} : { ip: from.ip }),
+    ...(userAgent === undefined ? {} : { userAgent }),
+  };
+  try {
+    switch (route) {
+      case "challenge":
+        return answer(deps.auth.challenge(), cors);
+      case "register": {
+        const minted = await deps.auth.register(args as unknown as AuthRegisterArgs, seen);
+        return answer(minted.session, cors, setCookie(deps, url.pathname, minted));
+      }
+      case "assert": {
+        const minted = await deps.auth.assert(args as unknown as AuthAssertArgs, seen);
+        return answer(minted.session, cors, setCookie(deps, url.pathname, minted));
+      }
+      case "refresh": {
+        const held = refreshCookie(request, deps);
+        if (held === undefined) {
+          return refusal("auth_invalid", "この要求には refresh token がありません", cors);
+        }
+        const minted = await deps.auth.refreshToken(held);
+        return answer(minted.session, cors, setCookie(deps, url.pathname, minted));
+      }
+    }
+  } catch (cause) {
+    if (cause instanceof OpError) return refusal(cause.code, cause.message, cors);
+    deps.log?.("an auth route failed", { route, error: String(cause) });
+    return refusal("internal_error", "この要求は処理できませんでした", cors);
+  }
+}
+
+/** The refresh token this request carries.
+ *
+ * Every cookie whose name has this instance's prefix is tried, because the name
+ * carries a digest of the subject and the caller has not said who they are yet.
+ * A browser holding two people's cookies presents both. */
+function refreshCookie(request: Request, deps: AuthRoutesDeps): string | undefined {
+  const header = request.headers.get("cookie");
+  if (header === null) return undefined;
+  for (const part of header.split(";")) {
+    const at = part.indexOf("=");
+    if (at === -1) continue;
+    const name = part.slice(0, at).trim();
+    if (!name.startsWith("__Secure-ccmsg-")) continue;
+    const value = part.slice(at + 1).trim();
+    if (deps.auth.records.byRefresh(value) !== undefined) return value;
+  }
+  // None of them is a standing token. The first one is answered with anyway, so
+  // that a value rotated away is seen as the reuse it is rather than as an
+  // absent cookie.
+  for (const part of header.split(";")) {
+    const at = part.indexOf("=");
+    if (at !== -1 && part.slice(0, at).trim().startsWith("__Secure-ccmsg-")) {
+      return part.slice(at + 1).trim();
+    }
+  }
+  return undefined;
+}
+
+/** The `Set-Cookie` for what the op just minted.
+ *
+ * The refresh token is answered by the op to its caller rather than left in a
+ * slot on the domain, so two exchanges in flight cannot hand one caller the
+ * other's token. */
+function setCookie(
+  deps: AuthRoutesDeps,
+  pathname: string,
+  minted: MintedSession,
+): Record<string, string> {
+  const name = cookieName(deps.self, minted.session.sub);
+  const maxAge = Math.max(0, Math.floor((minted.refresh.expires_at - Date.now()) / 1000));
+  return {
+    "set-cookie": [
+      `${name}=${minted.refresh.value}`,
+      "HttpOnly",
+      "Secure",
+      "SameSite=Strict",
+      `Path=${cookiePath(pathname)}`,
+      `Max-Age=${String(maxAge)}`,
+    ].join("; "),
+  };
+}
+
+function answer(
+  result: unknown,
+  cors: Record<string, string>,
+  extra: Record<string, string> = {},
+): Response {
+  return Response.json(result, { headers: { ...cors, ...extra } });
+}
+
+/** A refusal in the contract's own error shape, so a page reads one thing
+ * whether the op travelled over HTTP or over the WebSocket. */
+function refusal(code: ErrorCode | "bad_request", msg: string, cors: Record<string, string>) {
+  // A malformed request is the caller's to fix and an authentication failure is
+  // not, so the two do not share a status: 401 says "these credentials were not
+  // accepted", which is the wrong thing to tell somebody who left a field out.
+  const status =
+    code === "bad_request" || code === "invalid_args" ? 400 : code === "internal_error" ? 500 : 401;
+  return Response.json({ ok: false, error: { code, msg } }, { status, headers: cors });
+}
+
+async function body(request: Request): Promise<Record<string, unknown>> {
+  const declared = Number(request.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+    throw new Error(`the body is over ${String(MAX_BODY_BYTES)} bytes`);
+  }
+  const text = await request.text();
+  if (text.length > MAX_BODY_BYTES) {
+    throw new Error(`the body is over ${String(MAX_BODY_BYTES)} bytes`);
+  }
+  if (text === "") return {};
+  const parsed: unknown = JSON.parse(text);
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error("the body is a JSON object");
+  }
+  return parsed as Record<string, unknown>;
+}

package/src/auth/index.ts

@@ -0,0 +1,7 @@
+export * from "./admin.ts";
+export * from "./auth.ts";
+export * from "./cbor.ts";
+export * from "./http.ts";
+export * from "./records.ts";
+export * from "./topic.ts";
+export * from "./webauthn.ts";