sello 0.1.0

package/src/log/mock-log.ts

@@ -0,0 +1,170 @@
+import { sha256, assertTokenRef, toHex } from "../crypto/identifiers.ts";
+import { decodeProtectedHeader } from "../cose/protected-header.ts";
+import { decodeReceiptEnvelope } from "../cose/sign1.ts";
+import {
+  type CanonicalLogUrl,
+  assertCanonicalLogUrl,
+  logUrlsEqual,
+} from "./canonical-url.ts";
+import { type TransparencyLogQueryResult } from "./types.ts";
+
+export type MockInclusionProof = {
+  logUrl: CanonicalLogUrl;
+  index: number;
+  integratedTime: string;
+  envelopeHash: string;
+  proofHash: string;
+};
+
+export type MockLogEntry = {
+  logUrl: CanonicalLogUrl;
+  index: number;
+  integratedTime: string;
+  envelope: Uint8Array;
+  proof: MockInclusionProof;
+};
+
+export type MockLogQueryResult = TransparencyLogQueryResult & {
+  completeness: "complete";
+  entries: MockLogEntry[];
+};
+
+export class MockTransparencyLog {
+  readonly logUrl: CanonicalLogUrl;
+  #entries: MockLogEntry[] = [];
+  #tokenIndex = new Map<string, number[]>();
+
+  constructor(logUrl: CanonicalLogUrl) {
+    assertCanonicalLogUrl(logUrl, "logUrl");
+    this.logUrl = logUrl;
+  }
+
+  append(envelope: Uint8Array, integratedTime = nowUtcSeconds()): MockLogEntry {
+    assertBytes(envelope, "envelope");
+    assertUtcTimestamp(integratedTime, "integratedTime");
+
+    const decodedEnvelope = decodeReceiptEnvelope(envelope);
+    const protectedHeader = decodeProtectedHeader(decodedEnvelope.protectedBytes);
+    if (!logUrlsEqual(protectedHeader.sello_log_url, this.logUrl)) {
+      throw new TypeError("envelope sello_log_url must match mock log URL");
+    }
+
+    const index = this.#entries.length;
+    const proof = buildProof(this.logUrl, index, integratedTime, envelope);
+    const entry = freezeEntry({
+      logUrl: this.logUrl,
+      index,
+      integratedTime,
+      envelope,
+      proof,
+    });
+
+    this.#entries.push(entry);
+
+    const tokenRefHex = toHex(protectedHeader.sello_token_ref);
+    const indexes = this.#tokenIndex.get(tokenRefHex) ?? [];
+    indexes.push(index);
+    this.#tokenIndex.set(tokenRefHex, indexes);
+
+    return cloneEntry(entry);
+  }
+
+  queryByTokenRef(tokenRef: Uint8Array): MockLogQueryResult {
+    assertTokenRef(tokenRef, "tokenRef");
+    const indexes = this.#tokenIndex.get(toHex(tokenRef)) ?? [];
+
+    return {
+      completeness: "complete",
+      entries: indexes.map((index) => cloneEntry(this.#entries[index])),
+    };
+  }
+
+  verifyInclusionProof(entry: MockLogEntry): boolean {
+    try {
+      assertCanonicalLogUrl(entry.logUrl, "entry.logUrl");
+      if (!logUrlsEqual(entry.logUrl, this.logUrl)) {
+        return false;
+      }
+
+      const expected = buildProof(
+        this.logUrl,
+        entry.index,
+        entry.integratedTime,
+        entry.envelope,
+      );
+
+      return (
+        entry.proof.logUrl === expected.logUrl &&
+        entry.proof.index === expected.index &&
+        entry.proof.integratedTime === expected.integratedTime &&
+        entry.proof.envelopeHash === expected.envelopeHash &&
+        entry.proof.proofHash === expected.proofHash
+      );
+    } catch {
+      return false;
+    }
+  }
+}
+
+function buildProof(
+  logUrl: CanonicalLogUrl,
+  index: number,
+  integratedTime: string,
+  envelope: Uint8Array,
+): MockInclusionProof {
+  const envelopeHash = toHex(sha256(envelope));
+  const proofHash = toHex(
+    sha256(
+      new TextEncoder().encode(
+        `${logUrl}\n${index}\n${integratedTime}\n${envelopeHash}`,
+      ),
+    ),
+  );
+
+  return {
+    logUrl,
+    index,
+    integratedTime,
+    envelopeHash,
+    proofHash,
+  };
+}
+
+function freezeEntry(entry: MockLogEntry): MockLogEntry {
+  return {
+    logUrl: entry.logUrl,
+    index: entry.index,
+    integratedTime: entry.integratedTime,
+    envelope: new Uint8Array(entry.envelope),
+    proof: { ...entry.proof },
+  };
+}
+
+function cloneEntry(entry: MockLogEntry): MockLogEntry {
+  return {
+    logUrl: entry.logUrl,
+    index: entry.index,
+    integratedTime: entry.integratedTime,
+    envelope: new Uint8Array(entry.envelope),
+    proof: { ...entry.proof },
+  };
+}
+
+function nowUtcSeconds(): string {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+function assertUtcTimestamp(value: string, name: string): void {
+  if (
+    !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/.test(value) ||
+    Number.isNaN(Date.parse(value))
+  ) {
+    throw new TypeError(`${name} must be an RFC 3339 UTC timestamp`);
+  }
+}
+
+function assertBytes(value: unknown, name: string): asserts value is Uint8Array {
+  if (!(value instanceof Uint8Array)) {
+    throw new TypeError(`${name} must be a Uint8Array`);
+  }
+}

package/src/log/rekor.ts

@@ -0,0 +1,147 @@
+import { decodeProtectedHeader } from "../cose/protected-header.ts";
+import { decodeReceiptEnvelope } from "../cose/sign1.ts";
+import { assertTokenRef, toHex } from "../crypto/identifiers.ts";
+import {
+  type CanonicalLogUrl,
+  assertCanonicalLogUrl,
+  logUrlsEqual,
+} from "./canonical-url.ts";
+import {
+  type TransparencyLogEntry,
+  type TransparencyLogQueryResult,
+} from "./types.ts";
+
+export type RekorProofVerifier = (entry: TransparencyLogEntry) => boolean;
+
+export type RekorDiscoveredEntryInput = {
+  tokenRef?: Uint8Array;
+  logUrl?: CanonicalLogUrl;
+  index: number;
+  integratedTime: string;
+  envelope: Uint8Array;
+  proof: unknown;
+};
+
+export type RekorDiscoveryLogInput = {
+  logUrl: CanonicalLogUrl;
+  entries?: readonly RekorDiscoveredEntryInput[];
+  verifyInclusionProof?: RekorProofVerifier;
+};
+
+type IndexedEntry = {
+  tokenRefHex: string;
+  entry: TransparencyLogEntry;
+};
+
+export class RekorDiscoveryLog {
+  readonly logUrl: CanonicalLogUrl;
+  #entries: IndexedEntry[] = [];
+  #verifyInclusionProof: RekorProofVerifier;
+
+  constructor(input: RekorDiscoveryLogInput) {
+    assertCanonicalLogUrl(input.logUrl, "logUrl");
+    this.logUrl = input.logUrl;
+    this.#verifyInclusionProof = input.verifyInclusionProof ?? (() => false);
+
+    for (const entry of input.entries ?? []) {
+      this.addDiscoveredEntry(entry);
+    }
+  }
+
+  addDiscoveredEntry(input: RekorDiscoveredEntryInput): TransparencyLogEntry {
+    const entryLogUrl = input.logUrl ?? this.logUrl;
+    assertCanonicalLogUrl(entryLogUrl, "entry.logUrl");
+    assertUtcTimestamp(input.integratedTime, "integratedTime");
+    assertSafeIndex(input.index);
+    assertBytes(input.envelope, "envelope");
+
+    const tokenRefHex = input.tokenRef
+      ? tokenRefToHex(input.tokenRef)
+      : tokenRefFromEnvelope(input.envelope);
+
+    const entry = cloneEntry({
+      logUrl: entryLogUrl,
+      index: input.index,
+      integratedTime: input.integratedTime,
+      envelope: input.envelope,
+      proof: input.proof,
+    });
+
+    this.#entries.push({ tokenRefHex, entry });
+    return cloneEntry(entry);
+  }
+
+  queryByTokenRef(tokenRef: Uint8Array): TransparencyLogQueryResult {
+    const tokenRefHex = tokenRefToHex(tokenRef);
+
+    return {
+      completeness: "discovery-only",
+      entries: this.#entries
+        .filter((indexed) => indexed.tokenRefHex === tokenRefHex)
+        .map((indexed) => cloneEntry(indexed.entry)),
+    };
+  }
+
+  verifyInclusionProof(entry: TransparencyLogEntry): boolean {
+    try {
+      assertCanonicalLogUrl(entry.logUrl, "entry.logUrl");
+      if (!logUrlsEqual(entry.logUrl, this.logUrl)) {
+        return false;
+      }
+
+      return this.#verifyInclusionProof(entry);
+    } catch {
+      return false;
+    }
+  }
+}
+
+function tokenRefFromEnvelope(envelope: Uint8Array): string {
+  const decodedEnvelope = decodeReceiptEnvelope(envelope);
+  const protectedHeader = decodeProtectedHeader(decodedEnvelope.protectedBytes);
+  return tokenRefToHex(protectedHeader.sello_token_ref);
+}
+
+function tokenRefToHex(tokenRef: Uint8Array): string {
+  assertTokenRef(tokenRef, "tokenRef");
+  return toHex(tokenRef);
+}
+
+function cloneEntry(entry: TransparencyLogEntry): TransparencyLogEntry {
+  return {
+    logUrl: entry.logUrl,
+    index: entry.index,
+    integratedTime: entry.integratedTime,
+    envelope: new Uint8Array(entry.envelope),
+    proof: cloneProof(entry.proof),
+  };
+}
+
+function cloneProof(proof: unknown): unknown {
+  if (proof === null || typeof proof !== "object") {
+    return proof;
+  }
+
+  return globalThis.structuredClone(proof);
+}
+
+function assertUtcTimestamp(value: string, name: string): void {
+  if (
+    !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/.test(value) ||
+    Number.isNaN(Date.parse(value))
+  ) {
+    throw new TypeError(`${name} must be an RFC 3339 UTC timestamp`);
+  }
+}
+
+function assertSafeIndex(index: number): void {
+  if (!Number.isSafeInteger(index) || index < 0) {
+    throw new TypeError("index must be a non-negative safe integer");
+  }
+}
+
+function assertBytes(value: unknown, name: string): asserts value is Uint8Array {
+  if (!(value instanceof Uint8Array)) {
+    throw new TypeError(`${name} must be a Uint8Array`);
+  }
+}

package/src/log/types.ts

@@ -0,0 +1,27 @@
+import { type CanonicalLogUrl } from "./canonical-url.ts";
+
+export type LogCompleteness = "complete" | "discovery-only";
+
+export type TransparencyLogEntry = {
+  logUrl: CanonicalLogUrl;
+  index: number;
+  integratedTime: string;
+  envelope: Uint8Array;
+  proof: unknown;
+};
+
+export type TransparencyLogQueryResult = {
+  completeness: LogCompleteness;
+  entries: TransparencyLogEntry[];
+};
+
+export type VerificationLog = {
+  logUrl: CanonicalLogUrl;
+  queryByTokenRef(tokenRef: Uint8Array): TransparencyLogQueryResult;
+  verifyInclusionProof(entry: TransparencyLogEntry): boolean;
+};
+
+export type ReceiptSubmissionLog = {
+  logUrl: CanonicalLogUrl;
+  append(envelope: Uint8Array, integratedTime?: string): TransparencyLogEntry;
+};

package/src/mcp/middleware.ts

@@ -0,0 +1,198 @@
+import { createReceipt, type CreatedReceipt } from "../service/create-receipt.ts";
+import { verifySelloJwsToken } from "../token/jws-profile.ts";
+import { type ReceiptSubmissionLog } from "../log/types.ts";
+
+export type SelloMcpHandler<Request, Response> = (
+  request: Request,
+) => Response | Promise<Response>;
+
+export type SelloMcpValueOrGetter<Request, Value> =
+  | Value
+  | ((request: Request) => Value);
+
+export type SelloMcpReceiptEvent<Response = unknown> = {
+  resultStatus: "success" | "error" | "denied";
+  receipt: CreatedReceipt;
+  response?: Response;
+  error?: unknown;
+};
+
+export type SelloMcpMiddlewareInput<Request, Response> = {
+  handler: SelloMcpHandler<Request, Response>;
+  authorizationToken: SelloMcpValueOrGetter<Request, string | Uint8Array>;
+  tokenIssuerPublicKey: Uint8Array;
+  fallbackSelloLogs?: readonly string[];
+  serviceKid: Uint8Array;
+  servicePrivateKey: Uint8Array;
+  serviceIdentifier: string;
+  log: ReceiptSubmissionLog;
+  actionType?: string | ((request: Request) => string);
+  canonicalizeInput?: (request: Request) => Uint8Array;
+  canonicalizeOutput?: (response: Response) => Uint8Array;
+  canonicalizeError?: (error: unknown) => Uint8Array;
+  isDenied?: (request: Request) => boolean | Promise<boolean>;
+  deniedResponse?: (request: Request) => Response | Promise<Response>;
+  now?: () => string;
+  onReceipt?: (event: SelloMcpReceiptEvent<Response>) => void;
+};
+
+export class SelloMcpDeniedError extends Error {
+  readonly receipt: CreatedReceipt;
+
+  constructor(receipt: CreatedReceipt) {
+    super("MCP request denied by Sello middleware");
+    this.name = "SelloMcpDeniedError";
+    this.receipt = receipt;
+  }
+}
+
+export function createSelloMcpMiddleware<Request, Response>(
+  input: SelloMcpMiddlewareInput<Request, Response>,
+): SelloMcpHandler<Request, Response> {
+  return async (request: Request): Promise<Response> => {
+    const authorizationToken = resolveValue(input.authorizationToken, request);
+    const verifiedToken = verifySelloJwsToken({
+      authorizationToken,
+      issuerPublicKey: input.tokenIssuerPublicKey,
+    });
+    const baseReceiptInput = {
+      authorizationTokenBytes: verifiedToken.authorizationTokenBytes,
+      ownerHpkePublicKey: verifiedToken.ownerHpkePublicKey,
+      selloLogs: verifiedToken.selloLogs ?? input.fallbackSelloLogs ?? [],
+      serviceKid: input.serviceKid,
+      servicePrivateKey: input.servicePrivateKey,
+      serviceIdentifier: input.serviceIdentifier,
+      log: input.log,
+      actionType: resolveActionType(input.actionType, request),
+      actionInputBytes: (input.canonicalizeInput ?? canonicalJsonBytes)(request),
+      timestamp: (input.now ?? nowUtcSeconds)(),
+    };
+
+    if (input.isDenied && (await input.isDenied(request))) {
+      const response = input.deniedResponse
+        ? await input.deniedResponse(request)
+        : undefined;
+      const receipt = createReceipt({
+        ...baseReceiptInput,
+        actionOutputBytes: new Uint8Array(),
+        resultStatus: "denied",
+      });
+      input.onReceipt?.({ resultStatus: "denied", receipt, response });
+
+      if (input.deniedResponse) {
+        return response as Response;
+      }
+
+      throw new SelloMcpDeniedError(receipt);
+    }
+
+    let response: Response;
+    try {
+      response = await input.handler(request);
+    } catch (error) {
+      const receipt = createReceipt({
+        ...baseReceiptInput,
+        actionOutputBytes: (input.canonicalizeError ?? canonicalErrorBytes)(
+          error,
+        ),
+        resultStatus: "error",
+      });
+      input.onReceipt?.({ resultStatus: "error", receipt, error });
+      throw error;
+    }
+
+    const receipt = createReceipt({
+      ...baseReceiptInput,
+      actionOutputBytes: (input.canonicalizeOutput ?? canonicalJsonBytes)(
+        response,
+      ),
+      resultStatus: "success",
+    });
+    input.onReceipt?.({ resultStatus: "success", receipt, response });
+    return response;
+  };
+}
+
+export function canonicalJsonBytes(value: unknown): Uint8Array {
+  return new TextEncoder().encode(canonicalJson(value));
+}
+
+function canonicalJson(value: unknown): string {
+  if (value === null) {
+    return "null";
+  }
+
+  switch (typeof value) {
+    case "boolean":
+    case "number":
+    case "string":
+      return primitiveJson(value);
+    case "object":
+      if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(",")}]`;
+      }
+
+      return objectJson(value as Record<string, unknown>);
+    default:
+      throw new TypeError("value must be JSON-serializable");
+  }
+}
+
+function primitiveJson(value: boolean | number | string): string {
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    throw new TypeError("number must be finite");
+  }
+
+  return JSON.stringify(value);
+}
+
+function objectJson(value: Record<string, unknown>): string {
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new TypeError("object must be a plain JSON object");
+  }
+
+  const entries = Object.entries(value);
+  entries.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+
+  return `{${entries
+    .map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`)
+    .join(",")}}`;
+}
+
+function canonicalErrorBytes(error: unknown): Uint8Array {
+  if (error instanceof Error) {
+    return canonicalJsonBytes({
+      name: error.name,
+      message: error.message,
+    });
+  }
+
+  return canonicalJsonBytes({ error: String(error) });
+}
+
+function resolveValue<Request, Value>(
+  value: SelloMcpValueOrGetter<Request, Value>,
+  request: Request,
+): Value {
+  if (typeof value === "function") {
+    return (value as (request: Request) => Value)(request);
+  }
+
+  return value;
+}
+
+function resolveActionType<Request>(
+  actionType: SelloMcpMiddlewareInput<Request, unknown>["actionType"],
+  request: Request,
+): string {
+  if (typeof actionType === "function") {
+    return actionType(request);
+  }
+
+  return actionType ?? "tools/call";
+}
+
+function nowUtcSeconds(): string {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}