@aaes-ai/govern-sdk 0.0.0-stage → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 0.1.3 candidate
+
+- The package name is `@aaes-ai/govern-sdk`. npm still lists `@aaes-ai/sdk` through 0.1.2 until the rename release.
+- Minor-unit amounts above `Number.MAX_SAFE_INTEGER` are refused before sending, since the caller's exact amount may already be lost as a double.
+- A daemon-published spend cap (`spend_cap_minor`, federated `spend_cap.minor`) must be a nonnegative safe integer and `latency_added_ms` a finite nonnegative number; malformed values raise `AaesError` instead of being coerced, matching the Python and Go clients. An omitted cap still reads as `0`.
+
+## 0.1.2
+
+- Packaging/metadata-only patch: the registry description states the canonical product positioning (AI governance platform for the action layer: permissions, approvals by authorized persons, spending limits on routed actions, sealed decision record), keywords added for registry search, the homepage points to aaes.ai/developers/sdks.html, and the README opens with the product definition. No functional changes; the shipped code is unchanged.
+
+## 0.1.1
+
+- Packaging-only patch, published through the sdk-publish.yml npm trusted publisher with provenance. No functional changes; the shipped files are unchanged apart from the version field.
+- Verified the 0.1.0 tarball already ships `README.md` (extracted by the registry), so no packaging change was required for npm's README rendering.
+
+## 0.1.0 — candidate
+
+- Shared concurrent entitlement reads and prevented pre-refresh requests from replacing refreshed discovery data.
+- Forwarded optional caller-declared provenance on brokered requests so the daemon can apply the same risk rules as action requests.
+
+- Added bounded work, approval, entitlement and receipt reads.
+- Added agent-manager card reads/decisions, with explicit decision binding.
+- Added separate person-only access revocation client.
+- Preserved daemon-derived identity, fixed destinations, effect-key safeguards and redacted federated material.
+- Added native package consumer tests and release policy; TypeScript declarations and Python PEP 561 metadata.
+- README method list now advertises the complete read and card surface; every advertised method is covered by the package tests.
+
+- Reported deferred decisions instead of hiding them, and added resume across the three SDKs (Go `Resume`, Python `resume`, TypeScript `resume`): a deferred action is resubmitted unchanged under the same effect key via POST /v1/action/resume.
+- Added brokered resume (Go `ResumeBrokered`, Python `resume_brokered`, TypeScript `resumeBrokered`): a standing brokered deferral is revalidated and executed through the connector via POST /v1/brokered/resume, and a brokered resume never reports a grant without a confirmed execution as success.
+- Mapped a 404 from the resume routes to a refusal carrying the daemon's reason verbatim, falling back to the canned no-deferral sentence only when the 404 body states none; a missing deferral is answered without extra advice fetches, and decode errors name the resume route.
+- The TypeScript package publishes under the `@aaes-ai` npm scope (`@aaes-ai/sdk`), matching the GitHub organization and the Go module path; `@aaes/sdk` was never published, so the rename carried no migration cost.
+
+This entry describes the source candidate, not a published registry release.

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# AAES TypeScript / JavaScript SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+AAES (Autonomous Agentic Enterprise Systems) is an AI governance platform for the action layer: permissions, approvals by authorized persons, and spending limits on requests routed through it, with a sealed record of each completed decision. This package is its TypeScript/JavaScript client.
+
+ES module package `@aaes-ai/govern-sdk`, dependency-free runtime, with complete public TypeScript declarations and wire response types. Node 18+.
+
+```bash
+npm install ./sdk/typescript      # install local candidate
+node sdk/typescript/aaes.test.mjs   # node:test, nothing to install
+```
+
+These examples require SDK access, a running AAES daemon, and a token issued by
+your deployment operator. Set `AAES_ENDPOINT` and `AAES_TOKEN` first. The request
+reads permitted capabilities; it does not execute an agent action.
+
+```js
+import { Client } from "@aaes-ai/govern-sdk";
+
+try {
+  const result = await Client.fromEnv().capabilities();
+  console.log(`${result.capabilities.length} permitted capabilities`);
+} catch (error) {
+  console.error(String(error));
+  process.exitCode = 1;
+}
+```
+
+Methods: `capabilities`, `catalogue`, `health`, `action`, `brokered`,
+`resume`, `resumeBrokered`, `presentGrant`, `requestAccess`, `accessRequest`, `observe`, `refresh`,
+`federate`, the bounded reads `listTask`, `task`, `listApprovals`,
+`approval`, `listEntitlements`, `listReceipts`, `receipt`, the
+agent-manager card reads `managerCards` and `decideManagerCard`, the
+person-only operator client's `revokeAccessRequest`, and the exported
+`verifyHint(exportPath, publicKeyPath)`. Every method above is covered by
+this package's tests (`aaes.test.mjs`, `resume.test.mjs`, `read.test.mjs`, `federation.test.mjs`).
+
+What it deliberately does not do: `action()`, `requestAccess()` and
+`observe()` refuse any key they do not document, so `url`, `method`,
+`headers`, `credential`, `token`, `tenantId` and `actorId` cannot be
+smuggled in; the payload is checked against the field names the daemon refuses;
+tenant and actor come from `GET /v1/capabilities`; receipts are the daemon's
+bytes and are verified offline with `aaesctl verify`; a mutating call is
+retried only on opt-in, only after a 503, and only under the same effect key.
+
+Full guide: [docs/guides/INTEGRATION.md](../../docs/guides/INTEGRATION.md).
+
+A 503 response does not prove that the provider performed no action. Repeat only the identical request with its original effect key; never change the key to force a retry. The daemon retains the reservation and dispatch claim for uncertain outcomes and may answer the repeat with 409. It permits another dispatch only after proving that the previous attempt was never dispatched.
+
+## Candidate package and expanded contract
+
+See [SDK release policy](../RELEASE.md) and [complete operation/scope table](../CONTRACT.md). npm lists `@aaes-ai/sdk` through 0.1.2. This tree's package name is `@aaes-ai/govern-sdk`.
+
+Endpoint transport: bearer credentials require HTTPS. HTTP is accepted only
+for explicit loopback addresses (`localhost`, `127.0.0.0/8`, or `::1`); DNS
+resolution is never used to authorize plaintext transport.

package/aaes.d.mts

@@ -0,0 +1,180 @@
+import type * as Wire from './wire.js';
+export type { Task, TaskPage, Approval, ApprovalPage, EntitlementPage, ReceiptView, ReceiptPage, PageInfo, ManagerCard, ManagerCardsResponse, ManagerCardDecisionRecorded } from './wire.js';
+export const ENDPOINT_ENV: 'AAES_ENDPOINT';
+export const TOKEN_ENV: 'AAES_TOKEN';
+export const EFFECT_DENIED: 0;
+export const EFFECT_MINTED_UNUSED: 1;
+export const EFFECT_EXECUTED: 2;
+export const EFFECT_AUTHORIZED: 3;
+export const EFFECT_DEFERRED: 4;
+export class AaesError extends Error {}
+export class CallerRouteError extends AaesError {}
+export type JSONValue = string | number | boolean | null | JSONValue[] | { [key: string]: JSONValue };
+export type Payload = { [key: string]: JSONValue };
+export class RetryPolicy {
+  constructor(options?: { maxAttempts?: number; baseDelayMs?: number });
+  maxAttempts: number; baseDelayMs: number;
+  static default(): RetryPolicy;
+  attempts(identified: boolean, answer503: boolean): number;
+  delay(attempt: number): number;
+}
+export class Refusal {
+  constructor(status: number, reason: string, advice?: string[], retryable?: boolean);
+  status: number; reason: string; advice: string[]; retryable: boolean;
+  smallestChange(): string; toString(): string;
+}
+export interface Grant {
+  grantId: string; actorId: string; tenantId: string; capability: string; tier: string;
+  taskId: string; issuedAt: string; expiresAt: string; ttlSeconds: number;
+  spendCapMinor: number; spendCapCurrency: string; nonTransferable: boolean;
+  budgetGrantId: string; issuer: string; signature: string;
+}
+export interface GrantPresent {
+  grantId: string; actorId: string; tenantId: string; capability: string; tier: string;
+  taskId: string; issuedAt: string; expiresAt: string; spendCapMinor: number; spendCapCurrency: string;
+}
+export interface Receipt {
+  receiptId: string; intentId: string; tenantId: string; taskId: string; approvalId: string;
+  custody: string; grantId: string; effectId: string; effect: string; recordHash: string;
+  issuedAt: string; effectClass: number; railConfirmed: boolean; confirmedAt: string;
+  reportedBy: string; reportedAt: string; observedAt: string; reportedOutcome: string;
+  note: string; receiptHash: string; policyBundleHash: string; inputHash: string; engineVersion: string;
+}
+export class Decision {
+  constructor(fields?: Partial<Omit<Decision, 'ok'>>);
+  allowed: boolean; deferred: boolean; reason: string; intentId: string; grant: Grant | null; receipt: Receipt | null;
+  latencyAddedMs: number; refusal: Refusal | null; readonly ok: boolean;
+}
+export interface ExternalRef {
+  registry: string; kind: string; value: string; source: "registered";
+}
+export interface Action {
+  capability: string; action?: string; taskId?: string; callerTaskId?: string; effectKeyStep?: string;
+  amountMinor?: number; amountCurrency?: string; grantTtlMs?: number; correlationId?: string; parentIntentId?: string;
+  contractId?: string; model?: string; provenanceStatus?: "asserted" | "unknown"; externalRefs?: ExternalRef[];
+  payload?: Payload | null;
+}
+export interface BrokeredResult { decision: Decision; outcome: Partial<Wire.Outcome> }
+export interface Capability {
+  capabilityId: string; version: string; pinned: boolean; kind: string; owner: string;
+  riskTier: string; actions: string[]; resourceId: string; dataClass: string; custody: string;
+  enforcement: string; taskId: string; callerTaskId: string; expiresAt: string | null;
+  source: string; requestId: string; readonly name: string;
+}
+export interface Entitlement {
+  tenantId: string; actorId: string; capabilities: Capability[]; find(spelling: string): Capability | null;
+}
+export interface CataloguePolicy {
+  policyId: string; label: string; required: number; minHumans: number; classes: string[]; authority: string;
+}
+export interface CatalogueEntry {
+  capabilityId: string; version: string; kind: string; owner: string; riskTier: string; actions: string[];
+  resourceId: string; dataClass: string; custody: string; policy: CataloguePolicy;
+}
+export interface Catalog {
+  tenantId: string; actorId: string; requestable: CatalogueEntry[]; find(spelling: string): CatalogueEntry | null;
+}
+export interface AccessAsk {
+  capability: string; actions?: string[]; resourceId?: string; surfaceResourceId?: string; teamId?: string;
+  dataClass?: string; tier?: string; budgetMinor?: number; budgetCurrency?: string; ttlSeconds?: number; taskId?: string;
+  justification?: string; duration?: string; reviewDays?: number; windowStart?: string; windowEnd?: string;
+  windowTimezone?: string;
+}
+export interface AccessAnswer {
+  requestId: string; state: string; needed: Partial<Wire.Quorum>; alreadyHeld: boolean; refusal: Refusal | null;
+}
+export interface AccessView {
+  requestId: string; state: string; needed: Partial<Wire.Quorum>; tenantId: string; actorId: string;
+  capability: string; actions: string[]; resourceId: string; surfaceResourceId: string; teamId: string;
+  dataClass: string; tier: string; budgetMinor: number; budgetCurrency: string; ttlSeconds: number;
+  taskId: string; justification: string; duration: string; reviewTtlSeconds: number;
+  windowStart: string; windowEnd: string; windowTimezone: string; reviewRequired: boolean;
+  reviewedBy: string; reviewedAt: string | null; reviewed: boolean; approvalId: string;
+  approvals: Wire.AccessApprovalState[]; decidedBy: string[]; decidedAt: string | null;
+  expiresAt: string | null; createdAt: string | null; reason: string;
+}
+export interface Observation { intentId: string; effectId?: string; outcome?: string; observedAt?: string; note?: string }
+export interface ObserveResult {
+  intentId: string; receipt: Receipt | null; label: string; enforcement: string;
+  countsTowardCoverage: boolean; refusal: Refusal | null;
+}
+export interface FederateRequest {
+  capability: string; action?: string; taskId: string; effectKeyStep: string; amountMinor?: number;
+  amountCurrency?: string; grantTtlMs?: number; rotate?: boolean; correlationId?: string;
+}
+export class FederatedInstructions {
+  constructor(fields?: Partial<FederatedInstructions>);
+  backend: string; method: string; url: string; headers: Record<string, string>; form: Record<string, string>;
+  json: Record<string, unknown>; subjectTokenIn: string; subjectTokenField: string; subjectTokenType: string;
+  durationSeconds: number; documentation: string; notBuilt: string[]; notes: string[];
+  toString(): string;
+  toJSON(): { backend: string; method: string; url: string; subjectTokenField: string };
+}
+export class FederatedMaterial {
+  constructor(fields?: Partial<FederatedMaterial>);
+  kind: string; credential: Uint8Array; instructions: FederatedInstructions | null; expiresAt: string; audience: string;
+  toString(): string; toJSON(): { kind: string; redacted: true; expiresAt: string; audience: string };
+}
+export interface FederatedLocator { capability: string; endpoint: string; method: string; authority: string; resourceId: string }
+export interface FederatedRecord { intentId: string; mode: string; payloadSeen: boolean; markerReceiptHash: string; receiptId: string }
+export interface FederatedScope { capability: string; actions: string[]; resourceId: string; dataClass: string; tier: string; spendCapMinor: number; spendCapCurrency: string; scopeKey: string }
+export class FederatedGrant {
+  constructor(fields?: Partial<FederatedGrant>);
+  federationId: string; intentId: string; decisionGrantId: string; tenantId: string; actorId: string;
+  capability: string; capabilityVersion: string; actions: string[]; resourceId: string; taskId: string;
+  dataClass: string; tier: string; spendCapMinor: number; spendCapCurrency: string; scopeKey: string; backend: string;
+  locator: FederatedLocator; issuedAt: string; expiresAt: string; ttlSeconds: number;
+  material: FederatedMaterial; record: FederatedRecord;
+  scope(): FederatedScope; toString(): string;
+  toJSON(): { federation_id: string; intent_id: string; decision_grant_id: string; tenant_id: string;
+    actor_id: string; capability: string; actions: string[]; resource_id: string; task_id: string;
+    data_class: string; tier: string; scope_key: string; backend: string; locator: FederatedLocator;
+    issued_at: string; expires_at: string; ttl_seconds: number; material: ReturnType<FederatedMaterial['toJSON']>; record: FederatedRecord };
+}
+export type FederatedResult =
+  | { ok: true; allowed: true; reason: string; grant: FederatedGrant; refusal: null }
+  | { ok: false; allowed: false; reason: string; grant: null; refusal: Refusal };
+export interface ClientOptions {
+  endpoint?: string; token?: string; retries?: RetryPolicy; timeoutMs?: number; fetchImpl?: typeof fetch;
+}
+export interface PageFilters { limit?: number; cursor?: string }
+export interface TimeFilters extends PageFilters { since?: string; until?: string }
+export interface TaskFilters extends TimeFilters { state?: string; sponsor?: string; assignee?: string; overdue?: boolean }
+export interface ApprovalFilters extends TimeFilters { intentId?: string; taskId?: string; state?: 'pending' | 'all' }
+export interface EntitlementFilters extends PageFilters { actorId?: string; capability?: string; state?: 'all' | 'usable' | 'expired' | 'revoked' }
+export interface ReceiptFilters extends TimeFilters { intentId?: string; taskId?: string; effectClass?: 'denied' | 'minted_unused' | 'authorized' | 'executed'; custody?: string }
+export interface ManagerCardDecision { cardId: string; approvalId: string; payloadHash: string; policyId?: string; grant: boolean; reason?: string }
+export class Client {
+  constructor(options?: ClientOptions);
+  static fromEnv(options?: ClientOptions): Client;
+  refresh(): void;
+  entitlement(): Promise<Entitlement>;
+  capabilities(): Promise<Entitlement>;
+  catalog(): Promise<Catalog>;
+  health(): Promise<{ healthz: Wire.HealthResponse; readyz: Wire.ReadinessResponse; ready: boolean; reason: string }>;
+  action(action: Action): Promise<Decision>;
+  resume(action: Action): Promise<Decision>;
+  brokered(action: Action): Promise<BrokeredResult>;
+  resumeBrokered(action: Action): Promise<BrokeredResult>;
+  presentGrant(grantId: string): Promise<GrantPresent>;
+  federate(request: FederateRequest): Promise<FederatedResult>;
+  requestAccess(ask: AccessAsk): Promise<AccessAnswer>;
+  accessRequest(requestId: string): Promise<AccessView>;
+  observe(report: Observation): Promise<ObserveResult>;
+  listTask(filters?: TaskFilters): Promise<Wire.TaskPage>;
+  task(id: string): Promise<Wire.Task>;
+  listApprovals(filters?: ApprovalFilters): Promise<Wire.ApprovalPage>;
+  approval(id: string): Promise<Wire.Approval>;
+  listEntitlements(filters?: EntitlementFilters): Promise<Wire.EntitlementPage>;
+  listReceipts(filters?: ReceiptFilters): Promise<Wire.ReceiptPage>;
+  receipt(id: string): Promise<Wire.ReceiptView>;
+  managerCards(): Promise<Wire.ManagerCardsResponse>;
+  decideManagerCard(decision: ManagerCardDecision): Promise<Wire.ManagerCardDecisionRecorded>;
+}
+/** Requires a separately issued person token. The daemon authorizes each call. */
+export class OperatorClient extends Client {
+  static fromEnv(options?: ClientOptions): OperatorClient;
+  revokeAccessRequest(id: string, options?: { reason?: string }): Promise<AccessView>;
+}
+export function guardPayload(payload?: Payload | null): Payload | null;
+export function verifyHint(exportPath: string, publicKeyPath?: string): string;