sello 0.1.0

package/src/owner/verify.ts

@@ -0,0 +1,276 @@
+import { decodeProtectedHeader } from "../cose/protected-header.ts";
+import { decodeReceiptEnvelope, verifyReceiptEnvelope } from "../cose/sign1.ts";
+import { deriveTokenIdentifiers, toHex } from "../crypto/identifiers.ts";
+import { openReceiptBody } from "../hpke/receipt.ts";
+import {
+  type CanonicalLogUrl,
+  logUrlsEqual,
+} from "../log/canonical-url.ts";
+import {
+  type LogCompleteness,
+  type TransparencyLogEntry,
+  type VerificationLog,
+} from "../log/types.ts";
+import { decodeReceiptBody, type ReceiptBody } from "../receipt/body.ts";
+import {
+  type JsonIdentityRegistry,
+  assertKeyNotRevoked,
+  resolveServiceKey,
+} from "../registry/json-registry.ts";
+
+export type VerificationRejectionCode =
+  | "log_url_mismatch"
+  | "untrusted_log"
+  | "inclusion_proof_failed"
+  | "token_ref_mismatch"
+  | "unknown_kid"
+  | "revoked_key"
+  | "cose_signature_failed"
+  | "hpke_open_failed"
+  | "invalid_receipt_body";
+
+export type VerifyReceiptsInput = {
+  authorizationTokenBytes: Uint8Array;
+  trustedLogs: readonly VerificationLog[];
+  registry: JsonIdentityRegistry;
+  ownerPrivateKey: Uint8Array;
+};
+
+export type VerifiedReceipt = {
+  status: "valid" | "duplicate";
+  receipt: ReceiptBody;
+  serviceIdentifier: string;
+  kidHex: string;
+  tokenRefHex: string;
+  logUrl: CanonicalLogUrl;
+  logCompleteness: LogCompleteness;
+  integratedTime: string;
+  duplicateOf?: number;
+  sameSecondActivity: boolean;
+};
+
+export type RejectedReceipt = {
+  status: "rejected";
+  code: VerificationRejectionCode;
+  message: string;
+  logUrl?: CanonicalLogUrl;
+  integratedTime?: string;
+};
+
+export type VerifyReceiptsResult = {
+  receipts: VerifiedReceipt[];
+  rejected: RejectedReceipt[];
+};
+
+export function verifyReceipts(input: VerifyReceiptsInput): VerifyReceiptsResult {
+  const identifiers = deriveTokenIdentifiers(input.authorizationTokenBytes);
+  const trustedLogUrls = input.trustedLogs.map((log) => log.logUrl);
+  const receipts: VerifiedReceipt[] = [];
+  const rejected: RejectedReceipt[] = [];
+  const exactDedup = new Map<string, number>();
+  const sameSecond = new Map<string, number>();
+
+  for (const log of input.trustedLogs) {
+    const result = log.queryByTokenRef(identifiers.sello_token_ref);
+
+    for (const entry of result.entries) {
+      const verified = verifyOneEntry({
+        entry,
+        log,
+        logCompleteness: result.completeness,
+        trustedLogUrls,
+        tokenRef: identifiers.sello_token_ref,
+        registry: input.registry,
+        ownerPrivateKey: input.ownerPrivateKey,
+      });
+
+      if (verified.status === "rejected") {
+        rejected.push(verified);
+        continue;
+      }
+
+      const exactKey = buildExactDedupKey(verified);
+      const existingIndex = exactDedup.get(exactKey);
+
+      if (existingIndex !== undefined) {
+        receipts.push({
+          ...verified,
+          status: "duplicate",
+          duplicateOf: existingIndex,
+        });
+        continue;
+      }
+
+      const sameSecondKey = buildSameSecondKey(verified);
+      const sameSecondIndex = sameSecond.get(sameSecondKey);
+
+      if (sameSecondIndex !== undefined) {
+        receipts[sameSecondIndex] = {
+          ...receipts[sameSecondIndex],
+          sameSecondActivity: true,
+        };
+        verified.sameSecondActivity = true;
+      } else {
+        sameSecond.set(sameSecondKey, receipts.length);
+      }
+
+      exactDedup.set(exactKey, receipts.length);
+      receipts.push(verified);
+    }
+  }
+
+  return { receipts, rejected };
+}
+
+type VerifyOneEntryInput = {
+  entry: TransparencyLogEntry;
+  log: VerificationLog;
+  logCompleteness: LogCompleteness;
+  trustedLogUrls: readonly CanonicalLogUrl[];
+  tokenRef: Uint8Array;
+  registry: JsonIdentityRegistry;
+  ownerPrivateKey: Uint8Array;
+};
+
+function verifyOneEntry(input: VerifyOneEntryInput): VerifiedReceipt | RejectedReceipt {
+  let protectedHeaderBytes: Uint8Array;
+  let payload: Uint8Array;
+  let protectedHeader: ReturnType<typeof decodeProtectedHeader>;
+
+  try {
+    const envelope = decodeReceiptEnvelope(input.entry.envelope);
+    protectedHeaderBytes = envelope.protectedBytes;
+    payload = envelope.payload;
+    protectedHeader = decodeProtectedHeader(protectedHeaderBytes);
+  } catch (error) {
+    return reject("invalid_receipt_body", error, input.entry);
+  }
+
+  if (!logUrlsEqual(protectedHeader.sello_log_url, input.log.logUrl)) {
+    return reject(
+      "log_url_mismatch",
+      "receipt log URL does not match returning log",
+      input.entry,
+    );
+  }
+
+  if (!input.trustedLogUrls.some((logUrl) => logUrlsEqual(logUrl, input.log.logUrl))) {
+    return reject("untrusted_log", "returning log is not trusted", input.entry);
+  }
+
+  if (!bytesEqual(protectedHeader.sello_token_ref, input.tokenRef)) {
+    return reject(
+      "token_ref_mismatch",
+      "receipt token ref does not match requested token",
+      input.entry,
+    );
+  }
+
+  if (!input.log.verifyInclusionProof(input.entry)) {
+    return reject("inclusion_proof_failed", "inclusion proof failed", input.entry);
+  }
+
+  let service;
+  try {
+    service = resolveServiceKey(input.registry, protectedHeader.kid);
+  } catch (error) {
+    return reject("unknown_kid", error, input.entry);
+  }
+
+  try {
+    assertKeyNotRevoked(
+      input.registry,
+      protectedHeader.kid,
+      input.entry.integratedTime,
+    );
+  } catch (error) {
+    return reject("revoked_key", error, input.entry);
+  }
+
+  try {
+    verifyReceiptEnvelope({
+      envelope: input.entry.envelope,
+      servicePublicKey: service.publicKeyEd25519,
+    });
+  } catch (error) {
+    return reject("cose_signature_failed", error, input.entry);
+  }
+
+  let plaintext;
+  try {
+    plaintext = openReceiptBody({
+      payload,
+      ownerPrivateKey: input.ownerPrivateKey,
+      protectedHeaderBytes,
+      serviceIdentifier: service.serviceIdentifier,
+      selloTokenRef: protectedHeader.sello_token_ref,
+    });
+  } catch (error) {
+    return reject("hpke_open_failed", error, input.entry);
+  }
+
+  try {
+    return {
+      status: "valid",
+      receipt: decodeReceiptBody(plaintext),
+      serviceIdentifier: service.serviceIdentifier,
+      kidHex: toHex(protectedHeader.kid),
+      tokenRefHex: toHex(protectedHeader.sello_token_ref),
+      logUrl: input.log.logUrl,
+      logCompleteness: input.logCompleteness,
+      integratedTime: input.entry.integratedTime,
+      sameSecondActivity: false,
+    };
+  } catch (error) {
+    return reject("invalid_receipt_body", error, input.entry);
+  }
+}
+
+function buildExactDedupKey(record: VerifiedReceipt): string {
+  return [
+    buildSameSecondKey(record),
+    record.receipt["action-type"],
+    toHex(record.receipt["action-input-hash"]),
+    toHex(record.receipt["action-output-hash"]),
+  ].join("|");
+}
+
+function buildSameSecondKey(record: VerifiedReceipt): string {
+  return [
+    record.kidHex,
+    record.tokenRefHex,
+    truncateTimestampToSecond(record.receipt.timestamp),
+  ].join("|");
+}
+
+function truncateTimestampToSecond(timestamp: string): string {
+  return timestamp.replace(/\.\d+Z$/, "Z");
+}
+
+function reject(
+  code: VerificationRejectionCode,
+  error: unknown,
+  entry: TransparencyLogEntry,
+): RejectedReceipt {
+  return {
+    status: "rejected",
+    code,
+    message: error instanceof Error ? error.message : String(error),
+    logUrl: entry.logUrl,
+    integratedTime: entry.integratedTime,
+  };
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.byteLength !== b.byteLength) {
+    return false;
+  }
+
+  for (let index = 0; index < a.byteLength; index += 1) {
+    if (a[index] !== b[index]) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/receipt/body.ts

@@ -0,0 +1,210 @@
+import {
+  type CborMap,
+  type CborTagged,
+  cborTag,
+  decodeCbor,
+  encodeCbor,
+} from "../cbor.ts";
+import { assertAgentIdentifier } from "../crypto/identifiers.ts";
+
+export type ResultStatus = "success" | "error" | "denied";
+
+export type ReceiptBody = {
+  "agent-identifier": string;
+  "action-type": string;
+  "action-input-hash": Uint8Array;
+  "action-output-hash": Uint8Array;
+  "result-status": ResultStatus;
+  timestamp: string;
+  "service-defined-fields"?: CborMap;
+};
+
+export const ZERO_SHA256_DIGEST = new Uint8Array(32);
+
+const RESULT_STATUSES = new Set<ResultStatus>(["success", "error", "denied"]);
+const RECEIPT_KEYS = new Set([
+  "agent-identifier",
+  "action-type",
+  "action-input-hash",
+  "action-output-hash",
+  "result-status",
+  "timestamp",
+  "service-defined-fields",
+]);
+
+export function encodeReceiptBody(receipt: ReceiptBody): Uint8Array {
+  validateReceiptBody(receipt);
+
+  const map: CborMap = new Map([
+    ["agent-identifier", receipt["agent-identifier"]],
+    ["action-type", receipt["action-type"]],
+    ["action-input-hash", receipt["action-input-hash"]],
+    ["action-output-hash", receipt["action-output-hash"]],
+    ["result-status", receipt["result-status"]],
+    ["timestamp", cborTag(0, receipt.timestamp)],
+  ]);
+
+  if (receipt["service-defined-fields"]) {
+    map.set("service-defined-fields", receipt["service-defined-fields"]);
+  }
+
+  return encodeCbor(map);
+}
+
+export function decodeReceiptBody(bytes: Uint8Array): ReceiptBody {
+  const value = decodeCbor(bytes);
+
+  if (!(value instanceof Map)) {
+    throw new TypeError("receipt body must be a CBOR map");
+  }
+
+  for (const key of value.keys()) {
+    if (typeof key !== "string" || !RECEIPT_KEYS.has(key)) {
+      throw new TypeError(`receipt body contains unknown field ${String(key)}`);
+    }
+  }
+
+  const timestamp = value.get("timestamp");
+  const receipt: ReceiptBody = {
+    "agent-identifier": expectString(value, "agent-identifier"),
+    "action-type": expectString(value, "action-type"),
+    "action-input-hash": expectBytes(value, "action-input-hash"),
+    "action-output-hash": expectBytes(value, "action-output-hash"),
+    "result-status": expectResultStatus(value, "result-status"),
+    timestamp: expectTag0Timestamp(timestamp),
+  };
+
+  if (value.has("service-defined-fields")) {
+    const serviceFields = value.get("service-defined-fields");
+    if (!(serviceFields instanceof Map)) {
+      throw new TypeError("service-defined-fields must be a CBOR map");
+    }
+    assertServiceDefinedFields(serviceFields);
+    receipt["service-defined-fields"] = serviceFields;
+  }
+
+  validateReceiptBody(receipt);
+  return receipt;
+}
+
+export function validateReceiptBody(receipt: ReceiptBody): void {
+  assertObject(receipt, "receipt");
+  assertAgentIdentifier(receipt["agent-identifier"], "agent-identifier");
+  assertString(receipt["action-type"], "action-type");
+  assertSha256Digest(receipt["action-input-hash"], "action-input-hash");
+  assertSha256Digest(receipt["action-output-hash"], "action-output-hash");
+  assertResultStatus(receipt["result-status"], "result-status");
+  assertUtcTimestamp(receipt.timestamp, "timestamp");
+
+  if (
+    receipt["result-status"] === "denied" &&
+    !bytesEqual(receipt["action-output-hash"], ZERO_SHA256_DIGEST)
+  ) {
+    throw new TypeError("denied receipts must use all-zero action-output-hash");
+  }
+
+  if (receipt["service-defined-fields"] !== undefined) {
+    if (!(receipt["service-defined-fields"] instanceof Map)) {
+      throw new TypeError("service-defined-fields must be a Map");
+    }
+    assertServiceDefinedFields(receipt["service-defined-fields"]);
+  }
+}
+
+function expectString(map: CborMap, key: string): string {
+  const value = map.get(key);
+  assertString(value, key);
+  return value;
+}
+
+function expectBytes(map: CborMap, key: string): Uint8Array {
+  const value = map.get(key);
+  assertSha256Digest(value, key);
+  return value;
+}
+
+function expectResultStatus(map: CborMap, key: string): ResultStatus {
+  const value = map.get(key);
+  assertResultStatus(value, key);
+  return value;
+}
+
+function expectTag0Timestamp(value: unknown): string {
+  if (!isTagged(value) || value.tag !== 0 || typeof value.value !== "string") {
+    throw new TypeError("timestamp must be CBOR tag 0 containing a string");
+  }
+
+  assertUtcTimestamp(value.value, "timestamp");
+  return value.value;
+}
+
+function assertObject(value: unknown, name: string): asserts value is object {
+  if (typeof value !== "object" || value === null) {
+    throw new TypeError(`${name} must be an object`);
+  }
+}
+
+function assertString(value: unknown, name: string): asserts value is string {
+  if (typeof value !== "string") {
+    throw new TypeError(`${name} must be a string`);
+  }
+}
+
+function assertSha256Digest(value: unknown, name: string): asserts value is Uint8Array {
+  if (!(value instanceof Uint8Array) || value.byteLength !== 32) {
+    throw new TypeError(`${name} must be a 32-byte SHA-256 digest`);
+  }
+}
+
+function assertResultStatus(value: unknown, name: string): asserts value is ResultStatus {
+  if (typeof value !== "string" || !RESULT_STATUSES.has(value as ResultStatus)) {
+    throw new TypeError(`${name} must be success, error, or denied`);
+  }
+}
+
+function assertUtcTimestamp(value: unknown, name: string): asserts value is string {
+  assertString(value, name);
+
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/.test(value)) {
+    throw new TypeError(`${name} must be an RFC 3339 UTC timestamp`);
+  }
+
+  const parsed = Date.parse(value);
+  if (Number.isNaN(parsed)) {
+    throw new TypeError(`${name} must be a valid timestamp`);
+  }
+}
+
+function assertServiceDefinedFields(value: CborMap): void {
+  for (const [key, entryValue] of value.entries()) {
+    if (typeof key !== "string") {
+      throw new TypeError("service-defined-fields keys must be service identifiers");
+    }
+    if (!(entryValue instanceof Map)) {
+      throw new TypeError("service-defined-fields values must be CBOR maps");
+    }
+  }
+}
+
+function isTagged(value: unknown): value is CborTagged {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "tag" in value &&
+    "value" in value
+  );
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.byteLength !== b.byteLength) {
+    return false;
+  }
+
+  for (let index = 0; index < a.byteLength; index += 1) {
+    if (a[index] !== b[index]) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/registry/json-registry.ts

@@ -0,0 +1,233 @@
+import {
+  assertEd25519PublicKey,
+  assertEd25519Signature,
+  signEd25519,
+  verifyEd25519Signature,
+} from "../crypto/ed25519.ts";
+import { toHex } from "../crypto/identifiers.ts";
+
+export type RegistryEntry = {
+  kidHex: string;
+  serviceIdentifier: string;
+  publicKeyEd25519: Uint8Array;
+};
+
+export type RevocationEntry = {
+  kidHex: string;
+  revokedAt: string;
+};
+
+export type JsonIdentityRegistry = {
+  entries: Map<string, RegistryEntry>;
+  revoked: Map<string, RevocationEntry>;
+};
+
+export type LoadSignedRegistryInput = {
+  registryBytes: Uint8Array;
+  signatureBase64Url: string;
+  trustRootPublicKey: Uint8Array;
+};
+
+const textDecoder = new TextDecoder("utf-8", { fatal: true });
+const BASE64URL_32_BYTE_LENGTH = 43;
+
+export function signRegistryJson(
+  registryBytes: Uint8Array,
+  trustRootPrivateKey: Uint8Array,
+): string {
+  assertBytes(registryBytes, "registryBytes");
+  return base64urlEncode(signEd25519(registryBytes, trustRootPrivateKey));
+}
+
+export function loadSignedRegistry(
+  input: LoadSignedRegistryInput,
+): JsonIdentityRegistry {
+  verifyRegistrySignature(
+    input.registryBytes,
+    input.signatureBase64Url,
+    input.trustRootPublicKey,
+  );
+
+  return parseRegistry(input.registryBytes);
+}
+
+export function verifyRegistrySignature(
+  registryBytes: Uint8Array,
+  signatureBase64Url: string,
+  trustRootPublicKey: Uint8Array,
+): void {
+  assertBytes(registryBytes, "registryBytes");
+  assertEd25519PublicKey(trustRootPublicKey, "trustRootPublicKey");
+  const signature = base64urlDecode(signatureBase64Url, "registry signature");
+  assertEd25519Signature(signature, "registry signature");
+
+  if (!verifyEd25519Signature(registryBytes, signature, trustRootPublicKey)) {
+    throw new TypeError("registry signature verification failed");
+  }
+}
+
+export function parseRegistry(registryBytes: Uint8Array): JsonIdentityRegistry {
+  assertBytes(registryBytes, "registryBytes");
+  const parsed = JSON.parse(textDecoder.decode(registryBytes));
+
+  if (!isRecord(parsed)) {
+    throw new TypeError("registry must be a JSON object");
+  }
+
+  const entries = new Map<string, RegistryEntry>();
+  const revoked = parseRevoked(parsed.revoked);
+
+  for (const [kidHex, value] of Object.entries(parsed)) {
+    if (kidHex === "revoked") {
+      continue;
+    }
+
+    assertKidHex(kidHex, "registry kid");
+
+    if (!isRecord(value)) {
+      throw new TypeError(`registry entry ${kidHex} must be an object`);
+    }
+
+    const serviceIdentifier = value.service_identifier;
+    if (typeof serviceIdentifier !== "string" || serviceIdentifier.length === 0) {
+      throw new TypeError(`registry entry ${kidHex} service_identifier must be a non-empty string`);
+    }
+
+    const encodedPublicKey = value.public_key_ed25519;
+    if (typeof encodedPublicKey !== "string") {
+      throw new TypeError(`registry entry ${kidHex} public_key_ed25519 must be a string`);
+    }
+
+    const publicKeyEd25519 = base64urlDecodeFixed32(
+      encodedPublicKey,
+      `registry entry ${kidHex} public_key_ed25519`,
+    );
+
+    entries.set(kidHex, {
+      kidHex,
+      serviceIdentifier,
+      publicKeyEd25519,
+    });
+  }
+
+  return { entries, revoked };
+}
+
+export function resolveServiceKey(
+  registry: JsonIdentityRegistry,
+  kid: Uint8Array,
+): RegistryEntry {
+  const kidHex = toHex(kid);
+  const entry = registry.entries.get(kidHex);
+
+  if (!entry) {
+    throw new TypeError(`unknown kid ${kidHex}`);
+  }
+
+  return {
+    kidHex: entry.kidHex,
+    serviceIdentifier: entry.serviceIdentifier,
+    publicKeyEd25519: new Uint8Array(entry.publicKeyEd25519),
+  };
+}
+
+export function assertKeyNotRevoked(
+  registry: JsonIdentityRegistry,
+  kid: Uint8Array,
+  integratedTime?: string | Date,
+): void {
+  const kidHex = toHex(kid);
+  const revoked = registry.revoked.get(kidHex);
+
+  if (!revoked) {
+    return;
+  }
+
+  if (integratedTime === undefined) {
+    throw new TypeError(`kid ${kidHex} is revoked and requires verifiable integrated time`);
+  }
+
+  const integratedTimeMs =
+    integratedTime instanceof Date
+      ? integratedTime.getTime()
+      : parseUtcTimestamp(integratedTime, "integratedTime");
+  const revokedAtMs = parseUtcTimestamp(revoked.revokedAt, `revoked_at for ${kidHex}`);
+
+  if (integratedTimeMs >= revokedAtMs) {
+    throw new TypeError(`kid ${kidHex} was revoked at ${revoked.revokedAt}`);
+  }
+}
+
+function parseRevoked(value: unknown): Map<string, RevocationEntry> {
+  const revoked = new Map<string, RevocationEntry>();
+
+  if (value === undefined) {
+    return revoked;
+  }
+
+  if (!isRecord(value)) {
+    throw new TypeError("registry revoked must be an object");
+  }
+
+  for (const [kidHex, entry] of Object.entries(value)) {
+    assertKidHex(kidHex, "revoked kid");
+
+    if (!isRecord(entry) || typeof entry.revoked_at !== "string") {
+      throw new TypeError(`revoked entry ${kidHex} must contain revoked_at`);
+    }
+
+    parseUtcTimestamp(entry.revoked_at, `revoked_at for ${kidHex}`);
+    revoked.set(kidHex, { kidHex, revokedAt: entry.revoked_at });
+  }
+
+  return revoked;
+}
+
+function base64urlEncode(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString("base64url");
+}
+
+function base64urlDecodeFixed32(value: string, name: string): Uint8Array {
+  if (value.length !== BASE64URL_32_BYTE_LENGTH) {
+    throw new TypeError(`${name} must be base64url encoding of 32 bytes`);
+  }
+
+  const decoded = base64urlDecode(value, name);
+  assertEd25519PublicKey(decoded, name);
+  return decoded;
+}
+
+function base64urlDecode(value: string, name: string): Uint8Array {
+  if (!/^[A-Za-z0-9_-]+$/.test(value) || value.length % 4 === 1) {
+    throw new TypeError(`${name} must be unpadded base64url`);
+  }
+
+  return Uint8Array.from(Buffer.from(value, "base64url"));
+}
+
+function assertKidHex(value: string, name: string): void {
+  if (!/^(?:[0-9a-f]{2})+$/.test(value)) {
+    throw new TypeError(`${name} must be lowercase even-length hex`);
+  }
+}
+
+function parseUtcTimestamp(value: string, name: string): number {
+  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`);
+  }
+
+  return Date.parse(value);
+}
+
+function assertBytes(value: unknown, name: string): asserts value is Uint8Array {
+  if (!(value instanceof Uint8Array)) {
+    throw new TypeError(`${name} must be a Uint8Array`);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}