@comms-id/website-logo 0.0.0-stage → 0.3.2

package/dist/runtime/public-core.js

@@ -0,0 +1,16 @@
+// Runtime template: copied into every generated client package as src/runtime/public-core.ts.
+// The transport of a product whose contract says x-comms-id-auth { "kind": "none" } (ADR-0072):
+// public protocol metadata such as OpenID discovery and a JWKS. It sends no token, so it needs no
+// app id, no key and no relay. A signed product never uses it.
+import { resolveBaseUrl } from "./environment.js";
+const TRAILING_SLASHES = /\/+$/;
+export const createPublicTransport = (options = {}) => {
+    const base = resolveBaseUrl(options.environment, options.baseUrl).replace(TRAILING_SLASHES, "");
+    return {
+        urlFor: (operation) => `${base}${operation.path}`,
+        headers: () => Promise.resolve({}),
+        ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+        ...(options.deadlineMs === undefined ? {} : { deadlineMs: options.deadlineMs }),
+        ...(options.maxRetries === undefined ? {} : { maxRetries: options.maxRetries }),
+    };
+};

package/dist/runtime/server-core.d.ts

@@ -0,0 +1,26 @@
+import { type Environment } from "./environment.js";
+import type { TransportConfig } from "./http.js";
+import { type PrivateJwk } from "./sign.js";
+export declare const DEFAULT_BASE_URL: string;
+export interface ServerOptions {
+    /** Another host. It wins over `environment`. */
+    readonly baseUrl?: string;
+    /** The registered app id (COMMS_ID_CLIENT_ID). */
+    readonly clientId: string;
+    readonly deadlineMs?: number;
+    /** "live" (the default) or "test": synthetic replies for apps registered in the development directory. */
+    readonly environment?: Environment;
+    readonly fetch?: typeof fetch;
+    readonly maxRetries?: number;
+    readonly now?: () => number;
+    /** The app's private ML-DSA-87 key (COMMS_ID_PRIVATE_JWK). */
+    readonly privateJwk: PrivateJwk;
+    /** Seconds each signed token stays valid: 120 by default, 600 at most. */
+    readonly tokenLifetimeSeconds?: number;
+}
+/** What the service verifies: its audience and scope, written into the generated client. */
+export interface ServerTarget {
+    readonly audience: string;
+    readonly scope: string;
+}
+export declare const createServerTransport: (options: ServerOptions, target: ServerTarget) => TransportConfig;

package/dist/runtime/server-core.js

@@ -0,0 +1,39 @@
+// Runtime template: copied into every generated client package as src/runtime/server-core.ts.
+// Server entry only. The private key never leaves the consumer's server.
+import { BASE_URLS, resolveBaseUrl } from "./environment.js";
+import { CommsIdError } from "./errors.js";
+import { createTokenSigner } from "./sign.js";
+export const DEFAULT_BASE_URL = BASE_URLS.live;
+const TRAILING_SLASHES = /\/+$/;
+/** A transport that signs a fresh short-lived token for every call. */
+const notConfigured = (message) => new CommsIdError({ code: "NOT_CONFIGURED", message, status: 0, retryable: false });
+/** A client with no identified caller is a configuration error: it never sends an unsigned request. */
+const requireCaller = (options) => {
+    if (typeof options.clientId !== "string" || options.clientId.trim() === "") {
+        throw notConfigured("clientId is empty: set COMMS_ID_CLIENT_ID to your registered app id.");
+    }
+    const key = options.privateJwk;
+    if (key?.kty !== "AKP" || key.alg !== "ML-DSA-87" || typeof key.pub !== "string" || typeof key.priv !== "string") {
+        throw notConfigured("privateJwk is missing or not an ML-DSA-87 private key: set COMMS_ID_PRIVATE_JWK.");
+    }
+};
+export const createServerTransport = (options, target) => {
+    requireCaller(options);
+    const sign = createTokenSigner(options.privateJwk);
+    const base = resolveBaseUrl(options.environment, options.baseUrl).replace(TRAILING_SLASHES, "");
+    return {
+        urlFor: (operation) => `${base}${operation.path}`,
+        headers: async () => ({
+            authorization: `Bearer ${await sign({
+                clientId: options.clientId,
+                audience: target.audience,
+                scope: target.scope,
+                ...(options.tokenLifetimeSeconds === undefined ? {} : { lifetimeSeconds: options.tokenLifetimeSeconds }),
+                ...(options.now === undefined ? {} : { now: options.now }),
+            })}`,
+        }),
+        ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+        ...(options.deadlineMs === undefined ? {} : { deadlineMs: options.deadlineMs }),
+        ...(options.maxRetries === undefined ? {} : { maxRetries: options.maxRetries }),
+    };
+};

package/dist/runtime/sign.d.ts

@@ -0,0 +1,24 @@
+/** An ML-DSA-87 private key as a JWK: the key pair's private half stays on the consumer's server. */
+export interface PrivateJwk {
+    readonly alg: "ML-DSA-87";
+    readonly kty: "AKP";
+    /** The 32-byte seed, base64url. */
+    readonly priv: string;
+    /** The 2592-byte public key, base64url. */
+    readonly pub: string;
+}
+export interface TokenInput {
+    /** The service the token is for. */
+    readonly audience: string;
+    /** The registered app id, sent as the token issuer. */
+    readonly clientId: string;
+    /** Seconds the token stays valid: 120 by default, 600 at most. */
+    readonly lifetimeSeconds?: number;
+    readonly now?: () => number;
+    readonly scope: string;
+}
+/**
+ * Returns a function that signs one short-lived token for each call. The key is imported once.
+ * The token is a JWT with alg ML-DSA-87 and the claims iss, aud, sub, jti, iat, exp and scope.
+ */
+export declare const createTokenSigner: (privateJwk: PrivateJwk) => ((input: TokenInput) => Promise<string>);

package/dist/runtime/sign.js

@@ -0,0 +1,43 @@
+// Runtime template: copied into every generated client package as src/runtime/sign.ts.
+// Server entry only: the browser entry never imports this file. Web Crypto, no dependencies.
+// ML-DSA-87 needs Node.js 24.7 or later, or a Cloudflare Worker with the
+// webcrypto_modern_algorithms compatibility flag.
+const DEFAULT_LIFETIME_SECONDS = 120;
+const MAX_LIFETIME_SECONDS = 600;
+const encoder = new TextEncoder();
+const base64url = (bytes) => {
+    let binary = "";
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+};
+const encodeJson = (value) => base64url(encoder.encode(JSON.stringify(value)));
+/**
+ * Returns a function that signs one short-lived token for each call. The key is imported once.
+ * The token is a JWT with alg ML-DSA-87 and the claims iss, aud, sub, jti, iat, exp and scope.
+ */
+export const createTokenSigner = (privateJwk) => {
+    let key;
+    const importKey = () => {
+        key ??= crypto.subtle.importKey("jwk", privateJwk, { name: "ML-DSA-87" }, false, ["sign"]);
+        return key;
+    };
+    return async (input) => {
+        const lifetime = Math.min(Math.max(input.lifetimeSeconds ?? DEFAULT_LIFETIME_SECONDS, 1), MAX_LIFETIME_SECONDS);
+        const issuedAt = Math.floor((input.now?.() ?? Date.now()) / 1000);
+        const header = encodeJson({ alg: "ML-DSA-87" });
+        const payload = encodeJson({
+            scope: input.scope,
+            iss: input.clientId,
+            aud: input.audience,
+            sub: crypto.randomUUID(),
+            jti: crypto.randomUUID(),
+            iat: issuedAt,
+            exp: issuedAt + lifetime,
+        });
+        const signingInput = `${header}.${payload}`;
+        const signature = await crypto.subtle.sign({ name: "ML-DSA-87" }, await importKey(), encoder.encode(signingInput));
+        return `${signingInput}.${base64url(new Uint8Array(signature))}`;
+    };
+};

package/dist/runtime/validate.d.ts

@@ -0,0 +1,57 @@
+/** The JSON Schema subset that generated clients check, in a compact form the generator writes. */
+export type Schema = {
+    readonly t: "str";
+    readonly min?: number;
+    readonly max?: number;
+    readonly values?: readonly string[];
+    /** A JSON Schema pattern: checked in a request only. */
+    readonly pattern?: string;
+} | {
+    readonly t: "int" | "num";
+    readonly min?: number;
+    readonly max?: number;
+    /** exclusiveMinimum and exclusiveMaximum, checked in a request only. */
+    readonly exMin?: number;
+    readonly exMax?: number;
+    readonly values?: readonly number[];
+} | {
+    readonly t: "bool";
+} | {
+    readonly t: "null";
+} | {
+    readonly t: "any";
+} | {
+    readonly t: "const";
+    readonly value: string | number | boolean | null;
+} | {
+    readonly t: "arr";
+    readonly of: Schema;
+    readonly min?: number;
+    readonly max?: number;
+} | {
+    readonly t: "tup";
+    readonly of: readonly Schema[];
+} | {
+    readonly t: "map";
+    readonly of: Schema;
+} | {
+    readonly t: "obj";
+    readonly props: Readonly<Record<string, Schema>>;
+    readonly req: readonly string[];
+    readonly extra: boolean;
+} | {
+    readonly t: "any_of";
+    readonly of: readonly Schema[];
+};
+/**
+ * A request is checked against every constraint before it leaves the client. A response is
+ * checked for shape only: unknown properties, new enum values and size limits are accepted, so
+ * a service can add to a reply in a minor version without breaking an installed client.
+ */
+export type Mode = "request" | "response";
+export interface Issue {
+    readonly message: string;
+    readonly path: string;
+}
+/** Returns the problems found, at most eight, or an empty array when the value is acceptable. */
+export declare const validate: (schema: Schema, value: unknown, mode: Mode) => readonly Issue[];

package/dist/runtime/validate.js

@@ -0,0 +1,175 @@
+// Runtime template: copied into every generated client package as src/runtime/validate.ts.
+// It has no imports, so the copy is identical to this file.
+const MAX_ISSUES = 8;
+const describe = (value) => {
+    if (value === null) {
+        return "null";
+    }
+    return Array.isArray(value) ? "array" : typeof value;
+};
+const add = (issues, path, message) => {
+    if (issues.length < MAX_ISSUES) {
+        issues.push({ path, message });
+    }
+};
+const strictSize = (mode, size, min, max) => {
+    if (mode !== "request") {
+        return undefined;
+    }
+    if (min !== undefined && size < min) {
+        return `must be at least ${min}`;
+    }
+    if (max !== undefined && size > max) {
+        return `must be at most ${max}`;
+    }
+    return undefined;
+};
+/** A pattern the runtime cannot compile is not checked here: the service checks it. */
+const matches = (pattern, value) => {
+    try {
+        return new RegExp(pattern).test(value);
+    }
+    catch {
+        return true;
+    }
+};
+const checkString = (schema, value, path, mode, issues) => {
+    if (typeof value !== "string") {
+        add(issues, path, `expected a string, got ${describe(value)}`);
+        return;
+    }
+    const size = strictSize(mode, value.length, schema.min, schema.max);
+    if (size !== undefined) {
+        add(issues, path, `length ${size}`);
+    }
+    if (mode === "request" && schema.values !== undefined && !schema.values.includes(value)) {
+        add(issues, path, `must be one of ${schema.values.join(", ")}`);
+    }
+    if (mode === "request" && schema.pattern !== undefined && !matches(schema.pattern, value)) {
+        add(issues, path, `must match the pattern ${schema.pattern}`);
+    }
+};
+const checkNumber = (schema, value, path, mode, issues) => {
+    const ok = typeof value === "number" && Number.isFinite(value) && (schema.t === "num" || Number.isInteger(value));
+    if (!ok) {
+        add(issues, path, `expected ${schema.t === "int" ? "an integer" : "a number"}, got ${describe(value)}`);
+        return;
+    }
+    const size = strictSize(mode, value, schema.min, schema.max);
+    if (size !== undefined) {
+        add(issues, path, `value ${size}`);
+    }
+    if (mode === "request" && schema.exMin !== undefined && value <= schema.exMin) {
+        add(issues, path, `value must be greater than ${schema.exMin}`);
+    }
+    if (mode === "request" && schema.exMax !== undefined && value >= schema.exMax) {
+        add(issues, path, `value must be less than ${schema.exMax}`);
+    }
+    if (mode === "request" && schema.values !== undefined && !schema.values.includes(value)) {
+        add(issues, path, `must be one of ${schema.values.join(", ")}`);
+    }
+};
+const checkArray = (schema, value, path, mode, issues) => {
+    if (!Array.isArray(value)) {
+        add(issues, path, `expected an array, got ${describe(value)}`);
+        return;
+    }
+    const size = strictSize(mode, value.length, schema.min, schema.max);
+    if (size !== undefined) {
+        add(issues, path, `item count ${size}`);
+    }
+    value.forEach((item, index) => {
+        check(schema.of, item, `${path}[${index}]`, mode, issues);
+    });
+};
+const checkTuple = (schema, value, path, mode, issues) => {
+    if (!Array.isArray(value) || value.length !== schema.of.length) {
+        add(issues, path, `expected an array of ${schema.of.length} items`);
+        return;
+    }
+    schema.of.forEach((member, index) => {
+        check(member, value[index], `${path}[${index}]`, mode, issues);
+    });
+};
+const checkObject = (schema, value, path, mode, issues) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        add(issues, path, `expected an object, got ${describe(value)}`);
+        return;
+    }
+    const record = value;
+    for (const key of schema.req) {
+        if (!(key in record) || record[key] === undefined) {
+            add(issues, `${path}.${key}`, "is required");
+        }
+    }
+    for (const [key, member] of Object.entries(record)) {
+        const known = schema.props[key];
+        if (known !== undefined) {
+            if (member !== undefined) {
+                check(known, member, `${path}.${key}`, mode, issues);
+            }
+        }
+        else if (mode === "request" && !schema.extra) {
+            add(issues, `${path}.${key}`, "is not a known property");
+        }
+    }
+};
+const checkMap = (schema, value, path, mode, issues) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        add(issues, path, `expected an object, got ${describe(value)}`);
+        return;
+    }
+    for (const [key, member] of Object.entries(value)) {
+        if (member !== undefined) {
+            check(schema.of, member, `${path}.${key}`, mode, issues);
+        }
+    }
+};
+const checkUnion = (schema, value, path, mode, issues) => {
+    const matches = schema.of.some((member) => {
+        const nested = [];
+        check(member, value, path, mode, nested);
+        return nested.length === 0;
+    });
+    if (!matches) {
+        add(issues, path, "does not match any allowed shape");
+    }
+};
+const checkers = {
+    str: checkString,
+    int: checkNumber,
+    num: checkNumber,
+    arr: checkArray,
+    tup: checkTuple,
+    map: checkMap,
+    obj: checkObject,
+    any_of: checkUnion,
+};
+const checkSimple = (schema, value, path, issues) => {
+    if (schema.t === "bool" && typeof value !== "boolean") {
+        add(issues, path, `expected a boolean, got ${describe(value)}`);
+    }
+    else if (schema.t === "null" && value !== null) {
+        add(issues, path, `expected null, got ${describe(value)}`);
+    }
+    else if (schema.t === "const" && value !== schema.value) {
+        add(issues, path, `must be ${JSON.stringify(schema.value)}`);
+    }
+};
+const check = (schema, value, path, mode, issues) => {
+    if (issues.length >= MAX_ISSUES || schema.t === "any") {
+        return;
+    }
+    const checker = checkers[schema.t];
+    if (checker === undefined) {
+        checkSimple(schema, value, path, issues);
+        return;
+    }
+    checker(schema, value, path, mode, issues);
+};
+/** Returns the problems found, at most eight, or an empty array when the value is acceptable. */
+export const validate = (schema, value, mode) => {
+    const issues = [];
+    check(schema, value, "$", mode, issues);
+    return issues;
+};

package/dist/server.d.ts

@@ -0,0 +1,9 @@
+import { type WebsiteLogoClient } from "./generated/client.js";
+import { type ServerOptions } from "./runtime/server-core.js";
+export type { Environment } from "./runtime/environment.js";
+export type { PrivateJwk } from "./runtime/sign.js";
+export type { ServerOptions } from "./runtime/server-core.js";
+/** What the service verifies in the token. */
+export declare const AUDIENCE = "website-logo";
+export declare const SCOPE = "website-logo";
+export declare const createWebsiteLogoClient: (options: ServerOptions) => WebsiteLogoClient;

package/dist/server.js

@@ -0,0 +1,8 @@
+// Generated by @comms-id/forge-transformers from the service's OpenAPI contract. Do not edit: change the contract and regenerate.
+// Server entry: signs a short-lived token for each call with the app's private key.
+import { buildClient } from "./generated/client.js";
+import { createServerTransport } from "./runtime/server-core.js";
+/** What the service verifies in the token. */
+export const AUDIENCE = "website-logo";
+export const SCOPE = "website-logo";
+export const createWebsiteLogoClient = (options) => buildClient(createServerTransport(options, { audience: AUDIENCE, scope: SCOPE }));

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@comms-id/website-logo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.2",
+  "description": "Typed client for the Comms.ID Website logo API: a company's logo, resolved from its website address",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
+    "./controller": {
+      "types": "./dist/controller.d.ts",
+      "default": "./dist/controller.js"
+    },
+    "./fixtures": {
+      "types": "./dist/fixtures.d.ts",
+      "default": "./dist/fixtures.js"
+    },
+    "./descriptor": {
+      "types": "./dist/descriptor.d.ts",
+      "default": "./dist/descriptor.js"
+    }
+  },
+  "homepage": "https://comms.id",
+  "bugs": {
+    "url": "https://github.com/comms-id/platform/issues"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "COMMS.ID PTY LTD",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/comms-id/platform.git",
+    "directory": "packages/website-logo"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "typescript": "7.0.2",
+    "vitest": "5.0.4"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "biome check .",
+    "check-types": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }