@comms-id/asx 0.2.0

package/dist/runtime/sign.js

@@ -0,0 +1,41 @@
+// 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.
+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 EdDSA 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: "Ed25519" }, 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: "EdDSA" });
+        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: "Ed25519" }, 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 AsxClient } 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 = "asx-lookup";
+export declare const SCOPE = "asx";
+export declare const createAsxClient: (options: ServerOptions) => AsxClient;

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 = "asx-lookup";
+export const SCOPE = "asx";
+export const createAsxClient = (options) => buildClient(createServerTransport(options, { audience: AUDIENCE, scope: SCOPE }));

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@comms-id/asx",
+  "version": "0.2.0",
+  "description": "Typed client for the Comms.ID ASX API: ASX-listed companies: suggest as a user types, and look one up",
+  "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"
+    },
+    "./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/asx"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/node": "24.19.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.2"
+  },
+  "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"
+  }
+}