@kaana.ai/contracts 0.0.0-stage → 4.4.0

package/NOTICE

@@ -0,0 +1,21 @@
+============================================================================
+ NOTICE
+ @kaana.ai/contracts
+ Copyright (c) 2026-present The Oxy Collective, Inc.
+============================================================================
+
+This product is licensed under the Breathe License 1.0, license identifier
+LicenseRef-Breathe-1.0. See the LICENSE file in this directory. Commercial
+terms are available at
+https://github.com/OxyHQ/.github/blob/main/LICENSE-COMMERCIAL.md
+
+Attribution under Section 3.1 of the Breathe License is required of
+everyone, including paying commercial licensees, and cannot be waived.
+
+----------------------------------------------------------------------------
+ THIRD PARTY COMPONENTS
+----------------------------------------------------------------------------
+
+This package contains no third party source. Its dependencies are resolved
+and installed by the package manager and remain governed by their own
+licenses.

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `@kaana.ai/contracts` — the public contract of `https://kaana.ai/v1`.
+ *
+ * Every request and response of the public API, its stream events, the public
+ * error vocabulary, the catalogue with prices, power levels, audio
+ * capabilities and generation records, as Zod schemas with their inferred
+ * types. The shapes Oxy and Kaana exchange privately live under
+ * `@kaana.ai/contracts/internal` and are not part of the public API.
+ *
+ * Accounts, applications, `oxy_sk_…` keys, limits and billing are managed in
+ * Oxy Console (`https://console.oxy.so`), never here.
+ */
+export * from './public/audio.js';
+export * from './public/audioFormats.js';
+export * from './public/catalogue.js';
+export * from './public/chatCompletions.js';
+export * from './public/decisions.js';
+export * from './public/embeddings.js';
+export * from './public/errors.js';
+export * from './public/generations.js';
+export * from './public/identifiers.js';
+export * from './public/images.js';
+export * from './public/messages.js';
+export * from './public/money.js';
+export * from './public/policy.js';
+export * from './public/realtime.js';
+export * from './public/responses.js';
+export * from './public/streamEvents.js';
+export * from './public/version.js';

package/dist/index.js

@@ -0,0 +1,29 @@
+/**
+ * `@kaana.ai/contracts` — the public contract of `https://kaana.ai/v1`.
+ *
+ * Every request and response of the public API, its stream events, the public
+ * error vocabulary, the catalogue with prices, power levels, audio
+ * capabilities and generation records, as Zod schemas with their inferred
+ * types. The shapes Oxy and Kaana exchange privately live under
+ * `@kaana.ai/contracts/internal` and are not part of the public API.
+ *
+ * Accounts, applications, `oxy_sk_…` keys, limits and billing are managed in
+ * Oxy Console (`https://console.oxy.so`), never here.
+ */
+export * from './public/audio.js';
+export * from './public/audioFormats.js';
+export * from './public/catalogue.js';
+export * from './public/chatCompletions.js';
+export * from './public/decisions.js';
+export * from './public/embeddings.js';
+export * from './public/errors.js';
+export * from './public/generations.js';
+export * from './public/identifiers.js';
+export * from './public/images.js';
+export * from './public/messages.js';
+export * from './public/money.js';
+export * from './public/policy.js';
+export * from './public/realtime.js';
+export * from './public/responses.js';
+export * from './public/streamEvents.js';
+export * from './public/version.js';

package/dist/internal/attribution.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Canonical attribution carried by the signed envelope.
+ *
+ * Moved from `@oxy.so/contracts` 4.12.0 (`src/inference/attribution.ts`) by Kaana ADR 0002.
+ */
+import { z } from 'zod';
+/**
+ * The inference capability scopes the data plane needs to know about.
+ *
+ * A credential may carry many other Oxy scopes; only these cross the boundary,
+ * because the data plane's authorization questions are exactly "may this caller
+ * invoke", "may it read the catalogue", "may it read usage", "may it read or
+ * write routing", "may it read or write provider connections". Everything else
+ * is the control plane's business and is not the data plane's to hold.
+ */
+export declare const INFERENCE_SCOPES: readonly ["inference:invoke", "inference:models:read", "inference:usage:read", "inference:routing:read", "inference:routing:write", "inference:providers:read", "inference:providers:write"];
+export declare const inferenceScopeSchema: z.ZodEnum<{
+    "inference:invoke": "inference:invoke";
+    "inference:models:read": "inference:models:read";
+    "inference:usage:read": "inference:usage:read";
+    "inference:routing:read": "inference:routing:read";
+    "inference:routing:write": "inference:routing:write";
+    "inference:providers:read": "inference:providers:read";
+    "inference:providers:write": "inference:providers:write";
+}>;
+/**
+ * The financially responsible principal, and the ONLY identity a charge may be
+ * booked against.
+ *
+ * It is its own type — not a field on a larger principal object — precisely so
+ * that a function taking "who pays" cannot be handed a user, a session, a
+ * device or an application. It cannot be constructed from a delegated user id:
+ * the brands differ, and this object accepts no other key.
+ */
+export declare const billingPrincipalSchema: z.ZodObject<{
+    accountId: z.core.$ZodBranded<z.ZodString, "OxyAccountId", "out">;
+}, z.core.$strict>;
+/**
+ * Who authenticated, as resolved by the Oxy edge before a request is forwarded.
+ *
+ * Mirrors what a verified Oxy service token carries (`appId`, `credentialId`,
+ * `ownerAccountId`, `environment`, effective scopes) so that the two
+ * authentication paths — a machine API key and a first-party service token —
+ * produce one shape downstream. The data plane authorizes against this
+ * envelope; it does not re-derive access from its own database, because it has
+ * no account graph to re-derive it from.
+ */
+export declare const authenticatedPrincipalSchema: z.ZodObject<{
+    billing: z.ZodObject<{
+        accountId: z.core.$ZodBranded<z.ZodString, "OxyAccountId", "out">;
+    }, z.core.$strict>;
+    applicationId: z.ZodString;
+    credentialId: z.ZodString;
+    environment: z.ZodEnum<{
+        development: "development";
+        staging: "staging";
+        production: "production";
+    }>;
+    inferenceScopes: z.ZodArray<z.ZodEnum<{
+        "inference:invoke": "inference:invoke";
+        "inference:models:read": "inference:models:read";
+        "inference:usage:read": "inference:usage:read";
+        "inference:routing:read": "inference:routing:read";
+        "inference:routing:write": "inference:routing:write";
+        "inference:providers:read": "inference:providers:read";
+        "inference:providers:write": "inference:providers:write";
+    }>>;
+}, z.core.$strip>;
+/**
+ * The attribution block carried by every request, receipt and ledger record.
+ *
+ * `userId` is the OPTIONAL delegated end user — Alia's `X-Oxy-User-Id`. It is
+ * attribution only: it never changes which account is charged, never grants
+ * access, and lives outside {@link billingPrincipalSchema} so that no code path
+ * can read it as the payer.
+ *
+ * `requestId` is generated by the OXY EDGE, on admission and before
+ * authentication completes, and is always present (ADR 0007). Not by the data
+ * plane: a data plane that minted the correlation key could not correlate a
+ * request it never received, and the requests rejected at the edge are exactly
+ * the ones an operator most needs to find.
+ *
+ * `generationId` is present once a generation exists, which is why it is
+ * optional on a request and expected on a receipt. That one IS the data plane's,
+ * because only the data plane knows how many outputs a request produced.
+ */
+export declare const inferenceAttributionSchema: z.ZodObject<{
+    principal: z.ZodObject<{
+        billing: z.ZodObject<{
+            accountId: z.core.$ZodBranded<z.ZodString, "OxyAccountId", "out">;
+        }, z.core.$strict>;
+        applicationId: z.ZodString;
+        credentialId: z.ZodString;
+        environment: z.ZodEnum<{
+            development: "development";
+            staging: "staging";
+            production: "production";
+        }>;
+        inferenceScopes: z.ZodArray<z.ZodEnum<{
+            "inference:invoke": "inference:invoke";
+            "inference:models:read": "inference:models:read";
+            "inference:usage:read": "inference:usage:read";
+            "inference:routing:read": "inference:routing:read";
+            "inference:routing:write": "inference:routing:write";
+            "inference:providers:read": "inference:providers:read";
+            "inference:providers:write": "inference:providers:write";
+        }>>;
+    }, z.core.$strip>;
+    userId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "DelegatedUserId", "out">>;
+    requestId: z.ZodString;
+    generationId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type InferenceScope = z.infer<typeof inferenceScopeSchema>;
+export type BillingPrincipal = z.infer<typeof billingPrincipalSchema>;
+export type AuthenticatedPrincipal = z.infer<typeof authenticatedPrincipalSchema>;
+export type InferenceAttribution = z.infer<typeof inferenceAttributionSchema>;

package/dist/internal/attribution.js

@@ -0,0 +1,82 @@
+/**
+ * Canonical attribution carried by the signed envelope.
+ *
+ * Moved from `@oxy.so/contracts` 4.12.0 (`src/inference/attribution.ts`) by Kaana ADR 0002.
+ */
+import { z } from 'zod';
+import { delegatedUserIdSchema, generationIdSchema, inferenceEnvironmentSchema, oxyApplicationIdSchema, oxyCredentialIdSchema, requestIdSchema, } from '../public/identifiers.js';
+import { oxyAccountIdSchema } from './identifiers.js';
+/**
+ * The inference capability scopes the data plane needs to know about.
+ *
+ * A credential may carry many other Oxy scopes; only these cross the boundary,
+ * because the data plane's authorization questions are exactly "may this caller
+ * invoke", "may it read the catalogue", "may it read usage", "may it read or
+ * write routing", "may it read or write provider connections". Everything else
+ * is the control plane's business and is not the data plane's to hold.
+ */
+export const INFERENCE_SCOPES = [
+    'inference:invoke',
+    'inference:models:read',
+    'inference:usage:read',
+    'inference:routing:read',
+    'inference:routing:write',
+    'inference:providers:read',
+    'inference:providers:write',
+];
+export const inferenceScopeSchema = z.enum(INFERENCE_SCOPES);
+/**
+ * The financially responsible principal, and the ONLY identity a charge may be
+ * booked against.
+ *
+ * It is its own type — not a field on a larger principal object — precisely so
+ * that a function taking "who pays" cannot be handed a user, a session, a
+ * device or an application. It cannot be constructed from a delegated user id:
+ * the brands differ, and this object accepts no other key.
+ */
+export const billingPrincipalSchema = z
+    .object({
+    accountId: oxyAccountIdSchema,
+})
+    .strict();
+/**
+ * Who authenticated, as resolved by the Oxy edge before a request is forwarded.
+ *
+ * Mirrors what a verified Oxy service token carries (`appId`, `credentialId`,
+ * `ownerAccountId`, `environment`, effective scopes) so that the two
+ * authentication paths — a machine API key and a first-party service token —
+ * produce one shape downstream. The data plane authorizes against this
+ * envelope; it does not re-derive access from its own database, because it has
+ * no account graph to re-derive it from.
+ */
+export const authenticatedPrincipalSchema = z.object({
+    billing: billingPrincipalSchema,
+    applicationId: oxyApplicationIdSchema,
+    credentialId: oxyCredentialIdSchema,
+    environment: inferenceEnvironmentSchema,
+    inferenceScopes: z.array(inferenceScopeSchema),
+});
+/**
+ * The attribution block carried by every request, receipt and ledger record.
+ *
+ * `userId` is the OPTIONAL delegated end user — Alia's `X-Oxy-User-Id`. It is
+ * attribution only: it never changes which account is charged, never grants
+ * access, and lives outside {@link billingPrincipalSchema} so that no code path
+ * can read it as the payer.
+ *
+ * `requestId` is generated by the OXY EDGE, on admission and before
+ * authentication completes, and is always present (ADR 0007). Not by the data
+ * plane: a data plane that minted the correlation key could not correlate a
+ * request it never received, and the requests rejected at the edge are exactly
+ * the ones an operator most needs to find.
+ *
+ * `generationId` is present once a generation exists, which is why it is
+ * optional on a request and expected on a receipt. That one IS the data plane's,
+ * because only the data plane knows how many outputs a request produced.
+ */
+export const inferenceAttributionSchema = z.object({
+    principal: authenticatedPrincipalSchema,
+    userId: delegatedUserIdSchema.optional(),
+    requestId: requestIdSchema,
+    generationId: generationIdSchema.optional(),
+});

package/dist/internal/canonical.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Canonical JSON and the canonical input hash.
+ *
+ * Operations with a source approval (scoped execution, Private Auto, the Jev
+ * classifier) bind the exact input they were approved for. Kaana computes the
+ * hash of the input it is about to execute and Oxy compares it with the one
+ * the approval fixed (Kaana ADR 0002, decision 4), so both sides must hash the
+ * same bytes. This is that one definition.
+ *
+ * `canonicalJson` is moved from `@oxy.so/contracts` 4.12.0
+ * (`canonicalScopedExecutionJson`, `src/inference/scopedExecution.ts`), and Go
+ * restates it in `internal/contract/scoped_execution.go`.
+ */
+/**
+ * Canonical JSON wire bytes: recursive UTF-16 key order, JSON string/number
+ * encoding, arrays in order, no whitespace. Hash the whole signed input, not a
+ * reparsed/defaulted decision. Reject non-JSON values rather than dropping them.
+ */
+export declare function canonicalJson(value: unknown): string;
+/** The name scoped execution has always used for {@link canonicalJson}. */
+export declare const canonicalScopedExecutionJson: typeof canonicalJson;
+/**
+ * The canonical input hash: lowercase hex SHA-256 of {@link canonicalJson} of
+ * the request input, UTF-8 encoded.
+ *
+ * Asynchronous because it uses Web Crypto, which every runtime this package
+ * supports (Node 20+, Bun, browsers, Hermes with a crypto polyfill) provides
+ * without importing a platform module. Never logged or persisted: it binds
+ * transient signed bytes.
+ */
+export declare function canonicalInputSha256(input: unknown): Promise<string>;

package/dist/internal/canonical.js

@@ -0,0 +1,57 @@
+/**
+ * Canonical JSON and the canonical input hash.
+ *
+ * Operations with a source approval (scoped execution, Private Auto, the Jev
+ * classifier) bind the exact input they were approved for. Kaana computes the
+ * hash of the input it is about to execute and Oxy compares it with the one
+ * the approval fixed (Kaana ADR 0002, decision 4), so both sides must hash the
+ * same bytes. This is that one definition.
+ *
+ * `canonicalJson` is moved from `@oxy.so/contracts` 4.12.0
+ * (`canonicalScopedExecutionJson`, `src/inference/scopedExecution.ts`), and Go
+ * restates it in `internal/contract/scoped_execution.go`.
+ */
+/**
+ * Canonical JSON wire bytes: recursive UTF-16 key order, JSON string/number
+ * encoding, arrays in order, no whitespace. Hash the whole signed input, not a
+ * reparsed/defaulted decision. Reject non-JSON values rather than dropping them.
+ */
+export function canonicalJson(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return JSON.stringify(value);
+    if (typeof value === 'number' && Number.isFinite(value))
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        const entries = Array.from(value, (entry, index) => {
+            if (!(index in value))
+                throw new Error('Canonical JSON requires dense JSON arrays.');
+            return canonicalJson(entry);
+        });
+        return `[${entries.join(',')}]`;
+    }
+    if (typeof value === 'object' &&
+        value !== null &&
+        Object.getPrototypeOf(value) === Object.prototype) {
+        const entries = Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`);
+        return `{${entries.join(',')}}`;
+    }
+    throw new Error('Canonical JSON requires JSON wire values.');
+}
+/** The name scoped execution has always used for {@link canonicalJson}. */
+export const canonicalScopedExecutionJson = canonicalJson;
+/**
+ * The canonical input hash: lowercase hex SHA-256 of {@link canonicalJson} of
+ * the request input, UTF-8 encoded.
+ *
+ * Asynchronous because it uses Web Crypto, which every runtime this package
+ * supports (Node 20+, Bun, browsers, Hermes with a crypto polyfill) provides
+ * without importing a platform module. Never logged or persisted: it binds
+ * transient signed bytes.
+ */
+export async function canonicalInputSha256(input) {
+    const bytes = new TextEncoder().encode(canonicalJson(input));
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}