sello 0.1.0

package/src/sdk/index.ts

@@ -0,0 +1,22 @@
+import { createSelloService } from "./service.ts";
+import * as logs from "./logs.ts";
+
+export const sello = {
+  service: createSelloService,
+  logs,
+};
+
+export { createSelloService };
+export {
+  decodeBase64url,
+  encodeOwnerKey,
+  encodeServiceKey,
+  normalizeEd25519PrivateKey,
+  normalizeEd25519PublicKey,
+  normalizeHpkePrivateKey,
+  normalizeKid,
+  normalizeServiceKey,
+} from "./keys.ts";
+export * from "./logs.ts";
+export * from "./publisher.ts";
+export * from "./service.ts";

package/src/sdk/keys.ts

@@ -0,0 +1,191 @@
+import {
+  assertEd25519PrivateKey,
+  assertEd25519PublicKey,
+} from "../crypto/ed25519.ts";
+
+export type KeyInput = string | Uint8Array;
+
+export type ServiceKeyInput =
+  | string
+  | {
+      kid: KeyInput;
+      privateKey: KeyInput;
+    };
+
+export type NormalizedServiceKey = {
+  kid: Uint8Array;
+  privateKey: Uint8Array;
+};
+
+const textEncoder = new TextEncoder();
+
+export function normalizeServiceKey(
+  input: ServiceKeyInput | undefined,
+  fallbackKid?: KeyInput,
+): NormalizedServiceKey {
+  if (input === undefined) {
+    throw new TypeError("SELLO_SERVICE_KEY is required");
+  }
+
+  if (typeof input === "object" && !(input instanceof Uint8Array)) {
+    const kid = normalizeKid(input.kid, "serviceKey.kid");
+    const privateKey = normalizeEd25519PrivateKey(
+      input.privateKey,
+      "serviceKey.privateKey",
+    );
+    return { kid, privateKey };
+  }
+
+  if (typeof input !== "string") {
+    throw new TypeError("serviceKey must be a string or { kid, privateKey }");
+  }
+
+  const encoded = stripKnownServiceKeyPrefix(input);
+  const separator = encoded.indexOf(".");
+  if (separator !== -1) {
+    const kid = decodeBase64url(encoded.slice(0, separator), "service key kid");
+    const privateKey = normalizeEd25519PrivateKey(
+      encoded.slice(separator + 1),
+      "service key private key",
+    );
+    return { kid, privateKey };
+  }
+
+  if (fallbackKid === undefined) {
+    throw new TypeError(
+      "SELLO_SERVICE_KEY must include a kid, or SELLO_SERVICE_KID must be set",
+    );
+  }
+
+  return {
+    kid: normalizeKid(fallbackKid, "service kid"),
+    privateKey: normalizeEd25519PrivateKey(input, "service key private key"),
+  };
+}
+
+export function encodeServiceKey(
+  kid: Uint8Array,
+  privateKey: Uint8Array,
+  prefix = "sello_dev",
+): string {
+  assertBytes(kid, "kid");
+  assertEd25519PrivateKey(privateKey, "privateKey");
+  return `${prefix}_${base64urlEncode(kid)}.${base64urlEncode(privateKey)}`;
+}
+
+export function normalizeKid(input: KeyInput, name = "kid"): Uint8Array {
+  if (input instanceof Uint8Array) {
+    if (input.byteLength === 0) {
+      throw new TypeError(`${name} must not be empty`);
+    }
+    return new Uint8Array(input);
+  }
+
+  if (typeof input !== "string" || input.length === 0) {
+    throw new TypeError(`${name} must be a non-empty string or Uint8Array`);
+  }
+
+  return textEncoder.encode(input);
+}
+
+export function normalizeEd25519PrivateKey(
+  input: KeyInput,
+  name = "privateKey",
+): Uint8Array {
+  const key = normalizeFixedBase64urlKey(input, 32, name);
+  assertEd25519PrivateKey(key, name);
+  return key;
+}
+
+export function normalizeEd25519PublicKey(
+  input: KeyInput,
+  name = "publicKey",
+): Uint8Array {
+  const key = normalizeFixedBase64urlKey(input, 32, name);
+  assertEd25519PublicKey(key, name);
+  return key;
+}
+
+export function normalizeHpkePrivateKey(
+  input: KeyInput,
+  name = "ownerPrivateKey",
+): Uint8Array {
+  return normalizeFixedBase64urlKey(stripKnownOwnerKeyPrefix(input), 32, name);
+}
+
+export function encodeOwnerKey(privateKey: Uint8Array, prefix = "sello_owner_dev"): string {
+  assertByteLength(privateKey, 32, "privateKey");
+  return `${prefix}_${base64urlEncode(privateKey)}`;
+}
+
+export function base64urlEncode(bytes: Uint8Array): string {
+  assertBytes(bytes, "bytes");
+  return Buffer.from(bytes).toString("base64url");
+}
+
+export function decodeBase64url(value: string, name = "value"): 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 normalizeFixedBase64urlKey(
+  input: KeyInput,
+  length: number,
+  name: string,
+): Uint8Array {
+  if (input instanceof Uint8Array) {
+    assertByteLength(input, length, name);
+    return new Uint8Array(input);
+  }
+
+  if (typeof input !== "string") {
+    throw new TypeError(`${name} must be a string or Uint8Array`);
+  }
+
+  const decoded = decodeBase64url(input, name);
+  assertByteLength(decoded, length, name);
+  return decoded;
+}
+
+function stripKnownServiceKeyPrefix(input: string): string {
+  for (const prefix of ["sello_dev_", "sello_live_local_"]) {
+    if (input.startsWith(prefix)) {
+      return input.slice(prefix.length);
+    }
+  }
+
+  return input;
+}
+
+function stripKnownOwnerKeyPrefix(input: KeyInput): KeyInput {
+  if (typeof input !== "string") {
+    return input;
+  }
+
+  for (const prefix of ["sello_owner_dev_", "sello_owner_live_"]) {
+    if (input.startsWith(prefix)) {
+      return input.slice(prefix.length);
+    }
+  }
+
+  return input;
+}
+
+function assertByteLength(
+  value: unknown,
+  length: number,
+  name: string,
+): asserts value is Uint8Array {
+  if (!(value instanceof Uint8Array) || value.byteLength !== length) {
+    throw new TypeError(`${name} must be a ${length}-byte Uint8Array`);
+  }
+}
+
+function assertBytes(value: unknown, name: string): asserts value is Uint8Array {
+  if (!(value instanceof Uint8Array)) {
+    throw new TypeError(`${name} must be a Uint8Array`);
+  }
+}

package/src/sdk/logs.ts

@@ -0,0 +1,200 @@
+import { toHex } from "../crypto/identifiers.ts";
+import {
+  type CanonicalLogUrl,
+  assertCanonicalLogUrl,
+} from "../log/canonical-url.ts";
+import { MockTransparencyLog } from "../log/mock-log.ts";
+import {
+  type TransparencyLogEntry,
+  type TransparencyLogQueryResult,
+} from "../log/types.ts";
+import { base64urlEncode, decodeBase64url } from "./keys.ts";
+
+export type MaybePromise<T> = T | Promise<T>;
+
+export type SdkSubmissionLog = {
+  logUrl: CanonicalLogUrl;
+  append(
+    envelope: Uint8Array,
+    integratedTime?: string,
+  ): MaybePromise<TransparencyLogEntry>;
+};
+
+export type SelloHttpLogOptions = {
+  endpoint?: string;
+  logUrl?: string;
+  headers?: Record<string, string>;
+  fetch?: typeof fetch;
+};
+
+export type SerializedTransparencyLogEntry = {
+  logUrl: string;
+  index: number;
+  integratedTime: string;
+  envelope: string;
+  proof: unknown;
+};
+
+export function memory(url: string): MockTransparencyLog {
+  return new MockTransparencyLog(toCanonicalLogUrl(url));
+}
+
+export function http(url: string, options: SelloHttpLogOptions = {}): HttpSelloLog {
+  return new HttpSelloLog(url, options);
+}
+
+export async function queryHttpLogByTokenRef(
+  input: {
+    endpoint: string;
+    tokenRef: Uint8Array;
+    headers?: Record<string, string>;
+    fetch?: typeof fetch;
+  },
+): Promise<TransparencyLogQueryResult> {
+  const fetcher = input.fetch ?? fetch;
+  const url = buildUrl(input.endpoint, `/entries?sello_token_ref=${toHex(input.tokenRef)}`);
+  const response = await fetcher(url, {
+    method: "GET",
+    headers: input.headers,
+  });
+
+  if (!response.ok) {
+    throw new TypeError(`Sello log query failed with HTTP ${response.status}`);
+  }
+
+  const decoded = await response.json();
+  if (!isRecord(decoded) || !Array.isArray(decoded.entries)) {
+    throw new TypeError("Sello log query response must contain entries");
+  }
+
+  const completeness =
+    decoded.completeness === "complete" ? "complete" : "discovery-only";
+
+  return {
+    completeness,
+    entries: decoded.entries.map(deserializeEntry),
+  };
+}
+
+export class HttpSelloLog {
+  readonly logUrl: CanonicalLogUrl;
+  readonly endpoint: string;
+  readonly #headers?: Record<string, string>;
+  readonly #fetch: typeof fetch;
+
+  constructor(url: string, options: SelloHttpLogOptions = {}) {
+    this.logUrl = toCanonicalLogUrl(options.logUrl ?? url);
+    this.endpoint = normalizeEndpoint(options.endpoint ?? url);
+    this.#headers = options.headers;
+    this.#fetch = options.fetch ?? fetch;
+  }
+
+  async append(
+    envelope: Uint8Array,
+    integratedTime?: string,
+  ): Promise<TransparencyLogEntry> {
+    const response = await this.#fetch(buildUrl(this.endpoint, "/entries"), {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...this.#headers,
+      },
+      body: JSON.stringify({
+        logUrl: this.logUrl,
+        envelope: base64urlEncode(envelope),
+        ...(integratedTime === undefined ? {} : { integratedTime }),
+      }),
+    });
+
+    if (!response.ok) {
+      throw new TypeError(`Sello log append failed with HTTP ${response.status}`);
+    }
+
+    return deserializeEntry(await response.json());
+  }
+}
+
+export function serializeEntry(
+  entry: TransparencyLogEntry,
+): SerializedTransparencyLogEntry {
+  return {
+    logUrl: entry.logUrl,
+    index: entry.index,
+    integratedTime: entry.integratedTime,
+    envelope: base64urlEncode(entry.envelope),
+    proof: cloneJson(entry.proof),
+  };
+}
+
+export function deserializeEntry(input: unknown): TransparencyLogEntry {
+  if (!isRecord(input)) {
+    throw new TypeError("Sello log entry must be an object");
+  }
+
+  const { logUrl, index, integratedTime, envelope, proof } = input;
+  assertCanonicalLogUrl(logUrl, "entry.logUrl");
+
+  if (!Number.isSafeInteger(index) || index < 0) {
+    throw new TypeError("entry.index must be a non-negative safe integer");
+  }
+
+  if (
+    typeof integratedTime !== "string" ||
+    !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/.test(integratedTime)
+  ) {
+    throw new TypeError("entry.integratedTime must be an RFC 3339 UTC timestamp");
+  }
+
+  if (typeof envelope !== "string") {
+    throw new TypeError("entry.envelope must be base64url");
+  }
+
+  return {
+    logUrl,
+    index,
+    integratedTime,
+    envelope: decodeBase64url(envelope, "entry.envelope"),
+    proof: cloneJson(proof),
+  };
+}
+
+export function toCanonicalLogUrl(url: string): CanonicalLogUrl {
+  if (typeof url !== "string" || url.length === 0) {
+    throw new TypeError("log URL must be a non-empty string");
+  }
+
+  const parsed = new URL(url);
+  const path = parsed.pathname === "/" ? "/api" : parsed.pathname;
+  const protocol =
+    parsed.protocol === "http:" && isLocalHost(parsed.hostname) ? "https:" : parsed.protocol;
+  const canonical = `${protocol}//${parsed.host}${path}`;
+
+  assertCanonicalLogUrl(canonical, "logUrl");
+  return canonical;
+}
+
+function normalizeEndpoint(url: string): string {
+  const parsed = new URL(url);
+  const path = parsed.pathname === "/" ? "/api" : parsed.pathname.replace(/\/$/, "");
+  return `${parsed.protocol}//${parsed.host}${path}`;
+}
+
+function buildUrl(endpoint: string, path: string): string {
+  return `${endpoint.replace(/\/$/, "")}${path}`;
+}
+
+function isLocalHost(hostname: string): boolean {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function cloneJson(value: unknown): unknown {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+
+  return globalThis.structuredClone(value);
+}

package/src/sdk/publisher.ts

@@ -0,0 +1,145 @@
+import { type TransparencyLogEntry } from "../log/types.ts";
+import { type SdkSubmissionLog } from "./logs.ts";
+
+export type SubmitMode = "background" | "await";
+
+export type SelloSubmitOptions = {
+  mode?: SubmitMode;
+  maxPending?: number;
+  concurrency?: number;
+};
+
+export type PublishJob = {
+  envelope: Uint8Array;
+  integratedTime: string;
+};
+
+export type PublishResult = {
+  status: "submitted";
+  entry: TransparencyLogEntry;
+};
+
+export type DropEvent = {
+  envelope: Uint8Array;
+  integratedTime: string;
+  reason: "queue_full";
+};
+
+export type PublisherInput = {
+  log: SdkSubmissionLog;
+  submit?: SubmitMode | SelloSubmitOptions;
+  onSubmitError?: (error: unknown) => void;
+  onDrop?: (event: DropEvent) => void;
+};
+
+type QueuedJob = PublishJob & {
+  resolve: (entry: TransparencyLogEntry | undefined) => void;
+  reject: (error: unknown) => void;
+};
+
+export class BackgroundReceiptPublisher {
+  readonly #log: SdkSubmissionLog;
+  readonly #mode: SubmitMode;
+  readonly #maxPending: number;
+  readonly #concurrency: number;
+  readonly #onSubmitError?: (error: unknown) => void;
+  readonly #onDrop?: (event: DropEvent) => void;
+  readonly #queue: QueuedJob[] = [];
+  readonly #inFlight = new Set<Promise<void>>();
+
+  constructor(input: PublisherInput) {
+    this.#log = input.log;
+    const options = normalizeSubmitOptions(input.submit);
+    this.#mode = options.mode;
+    this.#maxPending = options.maxPending;
+    this.#concurrency = options.concurrency;
+    this.#onSubmitError = input.onSubmitError;
+    this.#onDrop = input.onDrop;
+  }
+
+  get mode(): SubmitMode {
+    return this.#mode;
+  }
+
+  async publish(job: PublishJob): Promise<TransparencyLogEntry | undefined> {
+    if (this.#mode === "await") {
+      return await this.#log.append(job.envelope, job.integratedTime);
+    }
+
+    if (this.#queue.length + this.#inFlight.size >= this.#maxPending) {
+      this.#onDrop?.({
+        envelope: new Uint8Array(job.envelope),
+        integratedTime: job.integratedTime,
+        reason: "queue_full",
+      });
+      return undefined;
+    }
+
+    const promise = new Promise<TransparencyLogEntry | undefined>((resolve, reject) => {
+      this.#queue.push({
+        envelope: new Uint8Array(job.envelope),
+        integratedTime: job.integratedTime,
+        resolve,
+        reject,
+      });
+    });
+    this.#drain();
+    return promise;
+  }
+
+  publishBackground(job: PublishJob): void {
+    void this.publish(job).catch((error) => {
+      this.#onSubmitError?.(error);
+    });
+  }
+
+  async flush(): Promise<void> {
+    while (this.#queue.length > 0 || this.#inFlight.size > 0) {
+      await Promise.allSettled([...this.#inFlight]);
+    }
+  }
+
+  #drain(): void {
+    while (this.#inFlight.size < this.#concurrency && this.#queue.length > 0) {
+      const job = this.#queue.shift() as QueuedJob;
+      const task = this.#submit(job).finally(() => {
+        this.#inFlight.delete(task);
+        this.#drain();
+      });
+      this.#inFlight.add(task);
+    }
+  }
+
+  async #submit(job: QueuedJob): Promise<void> {
+    try {
+      const entry = await this.#log.append(job.envelope, job.integratedTime);
+      job.resolve(entry);
+    } catch (error) {
+      this.#onSubmitError?.(error);
+      job.reject(error);
+    }
+  }
+}
+
+function normalizeSubmitOptions(
+  submit: SubmitMode | SelloSubmitOptions | undefined,
+): Required<SelloSubmitOptions> {
+  const options =
+    typeof submit === "string" || submit === undefined ? { mode: submit } : submit;
+  const mode = options.mode ?? "background";
+  if (mode !== "background" && mode !== "await") {
+    throw new TypeError("submit.mode must be background or await");
+  }
+
+  const maxPending = options.maxPending ?? 1000;
+  if (!Number.isSafeInteger(maxPending) || maxPending < 0) {
+    throw new TypeError("submit.maxPending must be a non-negative safe integer");
+  }
+
+  const concurrency = options.concurrency ?? 4;
+  if (!Number.isSafeInteger(concurrency) || concurrency < 1) {
+    throw new TypeError("submit.concurrency must be a positive safe integer");
+  }
+
+  return { mode, maxPending, concurrency };
+}