@dwk/solid-pod 0.1.0-beta.0

package/src/jwt.ts

@@ -0,0 +1,166 @@
+/**
+ * Minimal JWT decode and JWKS-based signature verification for the Resource
+ * Server edge.
+ *
+ * Solid-OIDC access tokens are asymmetrically signed by the issuer (the OP), so
+ * — unlike `@dwk/indieauth`'s HS256 self-issued tokens — verification needs the
+ * issuer's public JWKS rather than a shared secret. This module decodes the
+ * compact JWS, selects the key by `kid`/`kty`, and verifies the signature with
+ * Web Crypto. It performs no claim policy (issuer/audience/expiry) itself; that
+ * lives in `auth.ts`.
+ *
+ * Only asymmetric algorithms are accepted. `HS*` and `none` are refused: an
+ * access token must be signed by the issuer's private key, never a symmetric
+ * secret an RS could not safely hold.
+ */
+
+import { base64urlToBytes, base64urlToText } from "./encoding";
+
+/** Asymmetric JOSE algorithms accepted for issuer-signed access tokens. */
+export type JwtAlgorithm = "ES256" | "ES384" | "RS256" | "PS256";
+
+interface ImportAlg {
+  name: string;
+  namedCurve?: string;
+  hash?: string;
+}
+interface VerifyAlg {
+  name: string;
+  hash?: string;
+  saltLength?: number;
+}
+interface AlgSpec {
+  kty: "EC" | "RSA";
+  crv?: string;
+  importParams: ImportAlg;
+  verifyParams: VerifyAlg;
+}
+
+// We avoid the DOM lib's algorithm-parameter type names (not declared by
+// @cloudflare/workers-types); these objects are accepted structurally by
+// crypto.subtle.importKey / verify, mirroring the approach in `@dwk/dpop`.
+const ALGS: Record<JwtAlgorithm, AlgSpec> = {
+  ES256: {
+    kty: "EC",
+    crv: "P-256",
+    importParams: { name: "ECDSA", namedCurve: "P-256" },
+    verifyParams: { name: "ECDSA", hash: "SHA-256" },
+  },
+  ES384: {
+    kty: "EC",
+    crv: "P-384",
+    importParams: { name: "ECDSA", namedCurve: "P-384" },
+    verifyParams: { name: "ECDSA", hash: "SHA-384" },
+  },
+  RS256: {
+    kty: "RSA",
+    importParams: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+    verifyParams: { name: "RSASSA-PKCS1-v1_5" },
+  },
+  PS256: {
+    kty: "RSA",
+    importParams: { name: "RSA-PSS", hash: "SHA-256" },
+    verifyParams: { name: "RSA-PSS", saltLength: 32 },
+  },
+};
+
+/** A decoded JWT: its header, claims, and the raw segments for verification. */
+export interface DecodedJwt {
+  readonly header: Record<string, unknown>;
+  readonly payload: Record<string, unknown>;
+  readonly signingInput: string;
+  readonly signature: Uint8Array;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Decode a compact JWS into its header, payload, and signature. Returns `null`
+ * for anything that is not three base64url segments with JSON header/payload.
+ */
+export function decodeJwt(token: string): DecodedJwt | null {
+  if (typeof token !== "string") return null;
+  const segments = token.split(".");
+  if (segments.length !== 3) return null;
+  const [headerSeg, payloadSeg, signatureSeg] = segments as [
+    string,
+    string,
+    string,
+  ];
+  try {
+    const header = JSON.parse(base64urlToText(headerSeg)) as unknown;
+    const payload = JSON.parse(base64urlToText(payloadSeg)) as unknown;
+    if (!isObject(header) || !isObject(payload)) return null;
+    return {
+      header,
+      payload,
+      signingInput: `${headerSeg}.${payloadSeg}`,
+      signature: base64urlToBytes(signatureSeg),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Whether a JWK could verify a signature under the given algorithm. */
+function keyMatchesAlg(jwk: JsonWebKey, spec: AlgSpec): boolean {
+  if (jwk.kty !== spec.kty) return false;
+  if (spec.crv !== undefined && jwk.crv !== spec.crv) return false;
+  return true;
+}
+
+/**
+ * Verify `decoded`'s signature against a JWKS. Selects the verification key by
+ * `kid` when the header carries one, otherwise tries every key compatible with
+ * the header `alg`. Returns `true` on the first key that verifies.
+ */
+export async function verifyJwtSignature(
+  decoded: DecodedJwt,
+  jwks: readonly JsonWebKey[],
+): Promise<boolean> {
+  const alg = decoded.header.alg;
+  const spec = typeof alg === "string" ? ALGS[alg as JwtAlgorithm] : undefined;
+  if (!spec) return false;
+
+  const kid = decoded.header.kid;
+  const compatible = jwks.filter((jwk) => keyMatchesAlg(jwk, spec));
+
+  // When the token names a `kid`, pin verification to the key(s) carrying it.
+  // A token that names a `kid` matching no JWKS key is rejected rather than
+  // verified against unrelated keys: trying other keys would silently weaken
+  // `kid` pinning (a token claiming an unknown key still passing). Only when
+  // the header omits `kid` do we try every alg-compatible key.
+  let candidates = compatible;
+  if (typeof kid === "string") {
+    // `kid` is not in the standard JsonWebKey type but is carried by JWKS keys.
+    candidates = compatible.filter(
+      (jwk) => (jwk as { kid?: unknown }).kid === kid,
+    );
+    if (candidates.length === 0) return false;
+  }
+
+  for (const jwk of candidates) {
+    try {
+      const key = await crypto.subtle.importKey(
+        "jwk",
+        jwk,
+        spec.importParams,
+        false,
+        ["verify"],
+      );
+      const ok = await crypto.subtle.verify(
+        spec.verifyParams,
+        key,
+        decoded.signature,
+        new TextEncoder().encode(decoded.signingInput),
+      );
+      if (ok) return true;
+    } catch {
+      // A key that fails to import (wrong shape) simply does not match; try
+      // the next candidate rather than aborting the whole verification.
+    }
+  }
+  return false;
+}

package/src/ldp.ts

@@ -0,0 +1,99 @@
+/**
+ * Path and IRI helpers for the LDP resource/container model.
+ *
+ * Resources are keyed in the store by their URL pathname. Containers are the
+ * keys that end in `/`; everything else is a plain resource. ACL documents
+ * follow the Solid convention `<resource>.acl` (and `<container>.acl`). These
+ * helpers are pure string math so they unit-test without a Workers runtime.
+ */
+
+/** Whether a store key denotes an LDP container (trailing slash). */
+export function isContainer(path: string): boolean {
+  return path.endsWith("/");
+}
+
+/** Whether a path is an ACL document (`*.acl`). */
+export function isAclPath(path: string): boolean {
+  return path.endsWith(".acl");
+}
+
+/**
+ * Suffixes of server-governed auxiliary resources. Writing one requires
+ * `acl:Control` on the resource it governs (WAC), so a client `Slug` must
+ * never be allowed to mint one through a container `POST` (which is only
+ * authorized for `Append`/`Write` on the parent).
+ */
+const RESERVED_AUXILIARY_SUFFIXES = [".acl", ".meta"] as const;
+
+/** Whether a name/path ends in a reserved auxiliary suffix (`.acl`/`.meta`). */
+export function hasReservedAuxiliarySuffix(value: string): boolean {
+  return RESERVED_AUXILIARY_SUFFIXES.some((suffix) => value.endsWith(suffix));
+}
+
+/** The ACL document path that governs `path` (`<path>.acl`). */
+export function aclPath(path: string): string {
+  return `${path}.acl`;
+}
+
+/** The resource an ACL document governs (`<resource>.acl` → `<resource>`). */
+export function resourceForAcl(aclPathValue: string): string {
+  return aclPathValue.slice(0, -".acl".length);
+}
+
+/**
+ * The immediate parent container of `path`, or `null` for the root container.
+ * `"/a/b"` → `"/a/"`, `"/a/b/"` → `"/a/"`, `"/"` → `null`.
+ */
+export function parentContainer(path: string): string | null {
+  if (path === "/") return null;
+  const trimmed = isContainer(path) ? path.slice(0, -1) : path;
+  const slash = trimmed.lastIndexOf("/");
+  return slash < 0 ? "/" : trimmed.slice(0, slash + 1);
+}
+
+/**
+ * The ancestor containers of `path`, nearest first, up to and including the
+ * root container `"/"`.
+ */
+export function ancestorContainers(path: string): string[] {
+  const ancestors: string[] = [];
+  let current = parentContainer(path);
+  while (current !== null) {
+    ancestors.push(current);
+    current = parentContainer(current);
+  }
+  return ancestors;
+}
+
+/** Resolve a store key to its absolute resource IRI under `origin`. */
+export function toIri(origin: string, path: string): string {
+  return `${origin}${path}`;
+}
+
+const SLUG_UNSAFE = /[^A-Za-z0-9._~-]+/g;
+
+/**
+ * Pick a child key for a `POST` to `container`, honoring a client `Slug` when
+ * present and safe, and falling back to a random name. A trailing slash is
+ * appended when the new resource is itself a container.
+ */
+export function childKey(
+  container: string,
+  slug: string | null,
+  asContainer: boolean,
+): string {
+  const cleaned = slug
+    ?.trim()
+    .replace(SLUG_UNSAFE, "-")
+    .replace(/^-+|-+$/g, "");
+  // A Slug must never mint a reserved auxiliary resource (`.acl`/`.meta`):
+  // those govern a sibling's access/metadata and require `acl:Control` to
+  // write, which a container POST (authorized only for Append/Write on the
+  // parent) does not confer. Treat such a Slug as unusable and fall back to a
+  // random name, closing a privilege-escalation path (issue #28).
+  const name =
+    cleaned && cleaned.length > 0 && !hasReservedAuxiliarySuffix(cleaned)
+      ? cleaned
+      : crypto.randomUUID();
+  return `${container}${name}${asContainer ? "/" : ""}`;
+}

package/src/log.ts

@@ -0,0 +1,59 @@
+/**
+ * `@dwk/solid-pod` — structured observability event taxonomy.
+ *
+ * A Solid Pod authenticates DPoP-bound tokens at the edge and enforces WAC in
+ * the Durable Object; an auth/authz decision that is silently swallowed is an
+ * operational blind spot. Logging and metrics are opt-in via an injected
+ * {@link Logger} and {@link Metrics} (see `@dwk/log`) wired **once at the
+ * composition boundary** — the stateless front door. They **share this one
+ * vocabulary**: the same dotted event name is passed to the logger and the
+ * metrics sink so a log line and its counter line up.
+ *
+ * Because the Durable Object cannot receive injected functions across the
+ * isolate boundary, it signals its authorization outcomes back to the front door
+ * via an internal response header ({@link INTERNAL_HEADERS.outcome}); the front
+ * door — which holds the injected seams — emits the events and strips the header.
+ * This keeps the DO free of any logger and honors the composition contract.
+ *
+ * Fields follow the redaction policy: only machine-readable reason codes, HTTP
+ * method/status, and a sanitized agent host (`hostFromUrl`) — never tokens,
+ * proofs, resource paths, or bodies. See `spec/observability.md`.
+ *
+ * @packageDocumentation
+ */
+
+/** Stable event names emitted by `@dwk/solid-pod`. */
+export const SolidPodLogEvent = {
+  /**
+   * A presented credential failed edge authentication. Field: `reason` (an
+   * {@link AuthFailureReason}, e.g. `signature_invalid`, `dpop_invalid`).
+   */
+  AuthRejected: "solid.auth.rejected",
+  /** A request authenticated successfully at the edge. Field: `agentHost`. */
+  AuthAccepted: "solid.auth.accepted",
+  /** WAC refused the request in the Durable Object. Fields: `method`, `status` (401/403). */
+  AccessDenied: "solid.wac.denied",
+  /** A proof-less write was refused (DPoP required). Field: `method`. */
+  AnonymousWriteRefused: "solid.write.anonymous_refused",
+  /** A write's DPoP `jti` was replayed and the write was refused. Field: `method`. */
+  ReplayRejected: "solid.dpop.replay_rejected",
+} as const;
+
+/** Union of the event-name string literals in {@link SolidPodLogEvent}. */
+export type SolidPodLogEvent =
+  (typeof SolidPodLogEvent)[keyof typeof SolidPodLogEvent];
+
+/**
+ * Machine-readable outcome values the Durable Object sets on
+ * {@link INTERNAL_HEADERS.outcome} so the front door can emit the matching
+ * {@link SolidPodLogEvent}. Internal to the DO↔front-door contract; stripped
+ * before the response reaches the client.
+ */
+export const PodOutcome = {
+  WacDenied: "wac_denied",
+  AnonymousWriteRefused: "anon_write_refused",
+  Replay: "replay",
+} as const;
+
+/** Union of the outcome string literals in {@link PodOutcome}. */
+export type PodOutcome = (typeof PodOutcome)[keyof typeof PodOutcome];

package/src/negotiation.ts

@@ -0,0 +1,97 @@
+/**
+ * RDF content negotiation for reads.
+ *
+ * Maps an `Accept` header to a concrete RDF serialization `@dwk/rdf` can write,
+ * preferring the client's highest-q acceptable type and falling back to Turtle
+ * (the Solid default). Turtle and JSON-LD are the guaranteed minimum; the other
+ * Turtle-family types `@dwk/rdf` supports are offered too.
+ */
+
+import { formatForMediaType, type RdfFormat } from "@dwk/rdf";
+
+/** A negotiated serialization: the concrete media type and `@dwk/rdf` format. */
+export interface Negotiated {
+  readonly mediaType: string;
+  readonly format: RdfFormat;
+}
+
+/** Canonical media types offered on read, in server-preference order. */
+const OFFERED: readonly string[] = [
+  "text/turtle",
+  "application/ld+json",
+  "application/n-triples",
+  "application/trig",
+  "application/n-quads",
+];
+
+const DEFAULT: Negotiated = { mediaType: "text/turtle", format: "Turtle" };
+
+interface AcceptEntry {
+  readonly type: string;
+  readonly q: number;
+}
+
+/** Parse an `Accept` header into entries sorted by descending q-value. */
+function parseAccept(accept: string): AcceptEntry[] {
+  return accept
+    .split(",")
+    .map((part) => {
+      const [type, ...params] = part.split(";").map((s) => s.trim());
+      let q = 1;
+      for (const param of params) {
+        const m = /^q=([0-9.]+)$/.exec(param);
+        if (m) q = Number.parseFloat(m[1] as string);
+      }
+      return {
+        type: (type ?? "").toLowerCase(),
+        q: Number.isFinite(q) ? q : 0,
+      };
+    })
+    .filter((e) => e.type.length > 0)
+    .sort((a, b) => b.q - a.q);
+}
+
+/**
+ * Choose the RDF serialization to write for an `Accept` header, or `null` when
+ * the header is present but lists nothing this server can serve (the caller MUST
+ * then answer `406 Not Acceptable`). An absent/empty `Accept` or a `*` `/` `*`
+ * wildcard yields the Turtle default; concrete RDF media types and family
+ * wildcards (`text/*`, `application/*`) negotiate to a supported type.
+ */
+export function negotiateMediaType(accept: string | null): Negotiated | null {
+  if (!accept || accept.trim() === "") return DEFAULT;
+
+  for (const entry of parseAccept(accept)) {
+    if (entry.q === 0) continue;
+    if (entry.type === "*/*") return DEFAULT;
+
+    const essence = entry.type.split(";")[0]?.trim() ?? "";
+
+    // Read-only opt-in: a client asking for `application/json` gets JSON-LD.
+    // This alias lives here, not in `@dwk/rdf`'s RDF media-type registry, so an
+    // incoming `application/json` *request body* is never misparsed as RDF.
+    if (essence === "application/json") {
+      return { mediaType: "application/ld+json", format: "JSON-LD" };
+    }
+
+    const format = formatForMediaType(entry.type);
+    if (format) {
+      return { mediaType: essence || "text/turtle", format };
+    }
+
+    // Wildcard subtypes (`text/*`, `application/*`): pick the first offered
+    // type in that family.
+    const slash = entry.type.indexOf("/");
+    if (slash > 0 && entry.type.endsWith("/*")) {
+      const family = entry.type.slice(0, slash);
+      const offered = OFFERED.find((m) => m.startsWith(`${family}/`));
+      if (offered) {
+        return { mediaType: offered, format: formatForMediaType(offered)! };
+      }
+    }
+  }
+
+  // An `Accept` was supplied but nothing in it is acceptable: signal 406 rather
+  // than silently serving Turtle the client said it could not handle.
+  return null;
+}