@synoi/gap 0.1.0

package/src/cdro.ts

@@ -0,0 +1,92 @@
+/**
+ * cdro.ts -- GAP CDRO envelope.
+ *
+ * CDRO = Content-addressed, Deterministic, Replayable Object. Every GAP
+ * top-level record sits inside a `GapCdroEnvelope<TBody>`. The shape mirrors
+ * the GAP gateway reference implementation wire types.
+ *
+ * NOTE: this envelope shape is locally redeclared in @synoi/gap rather
+ * than imported from @synoi/sraid (which is being built in parallel). The two
+ * packages will be wired together in a follow-up. The wire format is
+ * identical, so cross-package compatibility is by-shape.
+ */
+
+export type GapObjectType =
+  // -- v1 REFERENCE IMPLEMENTATION TYPES (conformance-backed) --
+  // These 10 types are emitted by the v1 reference implementation and have
+  // conformance vectors in synoi-conformance. They are the only types that
+  // are considered SHIPPED for interoperability purposes.
+  | 'gap:capability_declaration'
+  | 'gap:capability_grant'
+  | 'gap:capability_invocation'
+  | 'gap:workflow_definition'
+  | 'gap:workflow_instance'
+  | 'gap:stage_transition'
+  | 'gap:channel_event'
+  | 'gap:decision_receipt'
+  | 'gap:revocation_event'
+  | 'gap:federation_handshake' // reserved for GAP 1.1 - not part of the active 1.0 conformance surface
+  // -- DRAFT TYPES (defined in spec; not yet emitted by the v1 reference
+  //    implementation; no conformance vector yet) --
+  // Do NOT rely on these for interoperability. They will graduate to the
+  // conformance-backed set when the reference implementation ships them and
+  // vectors are added to synoi-conformance.
+  | 'gap:break_glass_token'       // DRAFT: break-glass elevated access token
+  | 'gap:local_override_credential' // DRAFT: local policy override credential
+  | 'gap:lca_root'                // DRAFT: lowest-common-ancestor trust root
+  | 'gap:erasure_event'           // DRAFT: GDPR-style data erasure audit record
+  | 'gap:orchestration_chain'     // DRAFT: agent delegation chain (Item 1)
+  | 'gap:consent_record'          // DRAFT: consent version chain (Item 4)
+  | 'gap:pip_response'            // DRAFT: signed PIP response (Item 7)
+
+/** Current GAP wire version. CDROs that don't match this version are
+ *  rejected by validators. */
+export const GAP_VERSION = '1.0' as const
+export type GapVersion = typeof GAP_VERSION
+
+/**
+ * Fields excluded from the OID hash input (they are NOT part of the canonical
+ * body):  `oid`, `gap_version`, `signature`, `signature_key_id`, `supersedes`.
+ *
+ * Any future addition to this exclusion set constitutes a protocol version
+ * bump. Implementors must strip all five fields before passing the object to
+ * `computeGapOid` / `canonicalize`.
+ */
+export interface GapCdroEnvelope<TBody> {
+  /** Content-addressed identifier: `sha256:<hex>` over canonical body. */
+  oid: string
+  /** Object type discriminator, e.g. `gap:capability_grant`. */
+  type: GapObjectType
+  /** Wire version of the GAP protocol. */
+  gap_version: GapVersion
+  /** Tenant scope. CDROs never cross tenant boundaries implicitly. */
+  tenant_id: string
+  /** Server-clock millisecond timestamp at envelope construction. */
+  created_at_ms: number
+  /** Actor OID that created this CDRO. */
+  created_by: string
+  /** Type-specific payload. */
+  body: TBody
+  /** Optional Ed25519 signature, base64-encoded. */
+  signature?: string
+  /** Identifier of the public key that produced `signature`. */
+  signature_key_id?: string
+  /** OID of a prior CDRO that this one replaces. */
+  supersedes?: string
+}
+
+/**
+ * Payload shape passed to `computeGapOid` -- the envelope minus oid +
+ * gap_version + signature fields. Useful when builders are constructing a
+ * CDRO step-by-step.
+ *
+ * This is the canonical input shape for `computeGapOid` -- it already excludes
+ * `oid`, `gap_version`, `signature`, `signature_key_id`, and `supersedes`.
+ */
+export interface GapOidPayload<TBody> {
+  type: GapObjectType
+  tenant_id: string
+  created_at_ms: number
+  created_by: string
+  body: TBody
+}

package/src/channels.ts

@@ -0,0 +1,183 @@
+/**
+ * channels.ts -- channel taxonomy + adapter interface.
+ *
+ * Channels bridge GAP's abstract `actions`/`listen` model to concrete
+ * delivery surfaces (SMS, mobile push, home assistant, etc.).
+ *
+ * This file declares only the TYPES. Adapter implementations live in
+ * downstream packages (the gateway, vendor SDKs). The interface here is the
+ * contract those implementations satisfy.
+ */
+
+import type { GapCdroEnvelope } from './cdro.js'
+
+/** Built-in channel kinds. The `(string & {})` branch keeps the union open
+ *  for vendor-specific extensions (e.g. 'com.example.pager') while
+ *  preserving autocomplete on the canonical entries.
+ *
+ *  Connectivity categories:
+ *   Internet:     sms, voice, email, slack, mobile_push
+ *   LAN/Internet: sse, webhook
+ *   Local:        in_app, game_engine, home_assistant, desktop_overlay
+ *   Air-gapped:   local_terminal, hmi_panel, opc_ua_ack, local_signed_token
+ */
+export type ChannelKind =
+  // Internet channels
+  | 'sms'
+  | 'voice'
+  | 'email'
+  | 'slack'
+  | 'mobile_push'
+  // LAN/Internet channels
+  | 'sse'
+  | 'webhook'
+  // Local channels
+  | 'in_app'
+  | 'game_engine'
+  | 'home_assistant'
+  | 'desktop_overlay'
+  // Air-gapped / local enforcement point channels
+  | 'local_terminal'
+  | 'hmi_panel'
+  | 'opc_ua_ack'
+  | 'local_signed_token'
+  // Extensible for custom adapters; use reverse-domain prefix e.g. 'com.example.pager'
+  | (string & {})
+
+/** Subset of ChannelKind containing only the canonical (literal) values.
+ *  Useful for exhaustive switches in code that only handles built-ins. */
+export type CanonicalChannelKind =
+  | 'sms'
+  | 'voice'
+  | 'email'
+  | 'slack'
+  | 'mobile_push'
+  | 'sse'
+  | 'webhook'
+  | 'in_app'
+  | 'game_engine'
+  | 'home_assistant'
+  | 'desktop_overlay'
+  | 'local_terminal'
+  | 'hmi_panel'
+  | 'opc_ua_ack'
+  | 'local_signed_token'
+
+/** Ordered list of canonical channels, useful for menu UIs + tests. */
+export const CANONICAL_CHANNEL_KINDS: readonly CanonicalChannelKind[] = [
+  'sms',
+  'voice',
+  'email',
+  'slack',
+  'mobile_push',
+  'sse',
+  'webhook',
+  'in_app',
+  'game_engine',
+  'home_assistant',
+  'desktop_overlay',
+  'local_terminal',
+  'hmi_panel',
+  'opc_ua_ack',
+  'local_signed_token',
+] as const
+
+// -- Stage primitives that reference channels --------------------------------
+
+export interface StageAction {
+  channel: ChannelKind
+  method: string
+  params: Record<string, unknown>
+}
+
+export interface StageTransitionTarget {
+  next_stage_id?: string
+  bind?: Record<string, string>
+}
+
+export interface StageListen {
+  channel: ChannelKind
+  intent?: string
+  pattern?: string
+  event_kind?: string
+  next: StageTransitionTarget
+  /**
+   * When set, the gateway MUST verify that the channel event's `from` field
+   * matches this value before accepting it as a valid stage signal. For SMS
+   * channels this is the operator's registered phone number (E.164 format).
+   * For webhook channels this is the expected sender identity string.
+   *
+   * Required for stages that govern physical_safety=true or safety_class C
+   * capabilities. Absent means no sender-identity check is performed.
+   */
+  required_from_binding?: string
+}
+
+// -- ChannelEvent CDRO -------------------------------------------------------
+
+export interface ChannelEventBody {
+  channel: ChannelKind
+  event_kind: string
+  payload: Record<string, unknown>
+  observed_at_ms: number
+  /** Workflow context if this event originated from / is routed to a workflow. */
+  workflow_instance_oid?: string
+  stage_id?: string
+}
+
+export type ChannelEvent = GapCdroEnvelope<ChannelEventBody>
+
+// -- ChannelAdapter interface ------------------------------------------------
+
+export interface AdapterContext {
+  tenant_id: string
+  workflow_instance_oid: string
+  stage_id: string
+  scope_variables: Record<string, unknown>
+}
+
+export interface ActionResult {
+  ok: boolean
+  detail?: string
+  /** OID of a channel event spawned by the action, if any. */
+  spawned_event_oid?: string
+}
+
+export interface ListenHandle {
+  cancel(): void
+}
+
+/**
+ * Interface that every channel adapter must implement. Adapter
+ * implementations are out of scope for this types package -- they live in
+ * synoi-gateway and downstream packages.
+ */
+export interface ChannelAdapter {
+  /** Channel kind this adapter handles. */
+  kind: ChannelKind
+
+  /** Adapter capabilities -- which GAP listen/action shapes it supports. */
+  supports: {
+    actions: string[]
+    listens: Array<'intent' | 'pattern' | 'event_kind'>
+  }
+
+  /** Execute an action. Returns when complete or errors. */
+  performAction(spec: StageAction, context: AdapterContext): Promise<ActionResult>
+
+  /** Arm a listener. Returns a handle that can be cancelled. */
+  armListen(
+    spec: StageListen,
+    context: AdapterContext,
+    onMatch: (event: ChannelEvent) => void,
+  ): ListenHandle
+
+  /** Health check. */
+  health(): Promise<{ ok: boolean; detail?: string }>
+}
+
+export interface ChannelRegistry {
+  register(adapter: ChannelAdapter): void
+  get(kind: ChannelKind): ChannelAdapter | null
+  list(): ChannelAdapter[]
+}

package/src/constants.ts

@@ -0,0 +1,46 @@
+/**
+ * constants.ts -- well-known capability OIDs + channel kinds.
+ *
+ * Reserved OID strings for the GAP platform. These identifiers are stable
+ * across all conforming gateway implementations. Third-party implementations
+ * MUST NOT redefine them.
+ *
+ *   - DISCOVERY_QUERY_CAPABILITY   reserved for /by-grant discovery queries
+ *   - SKILL_CREATE_CAPABILITY      reserved for skill manifest upload
+ *   - VOICE_JOIN_CAPABILITY        reserved for voice bridge authorization
+ */
+
+import type { CanonicalChannelKind } from './channels.js'
+
+// -- Well-known capability names (dotted taxonomy) ---------------------------
+
+/** Capability that authorizes /by-grant discovery queries. */
+export const DISCOVERY_QUERY_CAPABILITY = 'gap.discovery.query' as const
+
+/** Capability that authorizes skill creation (skill manifest upload). */
+export const SKILL_CREATE_CAPABILITY = 'skill.create' as const
+
+/** Capability that authorizes joining a voice bridge call. */
+export const VOICE_JOIN_CAPABILITY = 'gap.voice.join' as const
+
+/** All well-known capability names, useful for tests + audit dashboards. */
+export const WELL_KNOWN_CAPABILITIES = [
+  DISCOVERY_QUERY_CAPABILITY,
+  SKILL_CREATE_CAPABILITY,
+  VOICE_JOIN_CAPABILITY,
+] as const
+
+export type WellKnownCapability = typeof WELL_KNOWN_CAPABILITIES[number]
+
+// -- Channel kind constants (mirror canonical list) --------------------------
+
+export const CHANNEL_VOICE: CanonicalChannelKind = 'voice'
+export const CHANNEL_SMS: CanonicalChannelKind = 'sms'
+export const CHANNEL_SLACK: CanonicalChannelKind = 'slack'
+export const CHANNEL_MOBILE_PUSH: CanonicalChannelKind = 'mobile_push'
+export const CHANNEL_HOME_ASSISTANT: CanonicalChannelKind = 'home_assistant'
+export const CHANNEL_DESKTOP_OVERLAY: CanonicalChannelKind = 'desktop_overlay'
+export const CHANNEL_EMAIL: CanonicalChannelKind = 'email'
+export const CHANNEL_IN_APP: CanonicalChannelKind = 'in_app'
+export const CHANNEL_GAME_ENGINE: CanonicalChannelKind = 'game_engine'
+export const CHANNEL_WEBHOOK: CanonicalChannelKind = 'webhook'

package/src/index.ts

@@ -0,0 +1,180 @@
+/**
+ * @synoi/gap -- public surface.
+ *
+ * Apache-2.0 TypeScript types + runtime validators for SynOI's
+ * GAP (Governed Action Protocol).
+ *
+ * The protocol itself is open under CC0; this package ships the wire-format
+ * types so any GAP implementation (third-party gateway, audit tool, vendor
+ * SDK) can speak the same wire format from a single source of truth.
+ */
+
+// -- CDRO envelope -----------------------------------------------------------
+export {
+  GAP_VERSION,
+} from './cdro.js'
+export type {
+  GapCdroEnvelope,
+  GapObjectType,
+  GapOidPayload,
+  GapVersion,
+} from './cdro.js'
+
+// -- Capabilities (declarations, grants, invocations) ------------------------
+export {
+  capabilityMatches,
+} from './capabilities.js'
+export type {
+  GapActorType,
+  Capability,
+  CapabilityDeclaration,
+  CapabilityDeclarationBody,
+  CapabilityGrant,
+  CapabilityGrantBody,
+  CapabilityInvocation,
+  CapabilityInvocationBody,
+  CapabilityPredicate,
+  GrantedCapabilityScope,
+  // Item 1: Agent Delegation Chain
+  DelegationStep,
+  OrchestrationChainBody,
+  // Item 2: MCP Tool-Call Governance
+  McpToolCallContext,
+  // Item 3: Token Budget Governance
+  TokenBudgetArgs,
+  // Item 4: Consent Version Chain
+  ConsentRecordBody,
+  // Item 5: Identity Binding
+  CredentialKind,
+  IdentityBinding,
+  // Item 6: Compartment-Based Access Scoping (fields added to existing types)
+  // Item 7: Signed PIP Response
+  ExternalPipArgs,
+  PipResponseBody,
+} from './capabilities.js'
+
+// -- Channels ----------------------------------------------------------------
+export {
+  CANONICAL_CHANNEL_KINDS,
+} from './channels.js'
+export type {
+  ActionResult,
+  AdapterContext,
+  CanonicalChannelKind,
+  ChannelAdapter,
+  ChannelEvent,
+  ChannelEventBody,
+  ChannelKind,
+  ChannelRegistry,
+  ListenHandle,
+  StageAction,
+  StageListen,
+  StageTransitionTarget,
+} from './channels.js'
+
+// -- Workflows ---------------------------------------------------------------
+export type {
+  OptionalEffect,
+  StageSafety,
+  StageTransition,
+  StageTransitionBody,
+  StageTransitionReason,
+  WorkflowDefinition,
+  WorkflowDefinitionBody,
+  WorkflowInstance,
+  WorkflowInstanceBody,
+  WorkflowStage,
+  WorkflowStageDefinition,
+  WorkflowTrigger,
+  WorkflowTriggerKind,
+} from './workflows.js'
+
+// -- Receipts + failures -----------------------------------------------------
+export {
+  isGapFailure,
+} from './receipts.js'
+export type {
+  GapDecisionReceipt,
+  GapDecisionReceiptBody,
+  GapFailure,
+  GapFailureReason,
+  DecisionStatus,
+  DecisionSubjectKind,
+  // Item 3: Token Budget Governance
+  TokenConsumption,
+} from './receipts.js'
+
+// -- Revocations -------------------------------------------------------------
+export {
+  revokeGapObject,
+} from './revocations.js'
+export type {
+  RevocationEvent,
+  RevocationEventBody,
+  RevocationTargetKind,
+} from './revocations.js'
+
+// -- Constants ---------------------------------------------------------------
+export {
+  CHANNEL_DESKTOP_OVERLAY,
+  CHANNEL_EMAIL,
+  CHANNEL_GAME_ENGINE,
+  CHANNEL_HOME_ASSISTANT,
+  CHANNEL_IN_APP,
+  CHANNEL_MOBILE_PUSH,
+  CHANNEL_SLACK,
+  CHANNEL_SMS,
+  CHANNEL_VOICE,
+  CHANNEL_WEBHOOK,
+  DISCOVERY_QUERY_CAPABILITY,
+  SKILL_CREATE_CAPABILITY,
+  VOICE_JOIN_CAPABILITY,
+  WELL_KNOWN_CAPABILITIES,
+} from './constants.js'
+export type {
+  WellKnownCapability,
+} from './constants.js'
+
+// -- OID + canonicalize ------------------------------------------------------
+export {
+  computeGapOid,
+} from './oid.js'
+export {
+  canonicalize,
+} from './canonicalize.js'
+
+// -- Validators --------------------------------------------------------------
+export type {
+  ValidationResult,
+} from './validate.js'
+export {
+  validateGapDecisionReceipt,
+  validateGapDecisionReceiptBody,
+  validateCapabilityDeclaration,
+  validateCapabilityDeclarationBody,
+  validateCapabilityGrant,
+  validateCapabilityGrantBody,
+  validateCapabilityInvocation,
+  validateCapabilityInvocationBody,
+  validateChannelEvent,
+  validateChannelEventBody,
+  validateRevocationEvent,
+  validateRevocationEventBody,
+  validateStageTransition,
+  validateStageTransitionBody,
+  validateWorkflowDefinition,
+  validateWorkflowDefinitionBody,
+  validateWorkflowInstance,
+  validateWorkflowInstanceBody,
+  // Item 1: Agent Delegation Chain
+  validateOrchestrationChainBody,
+  validateOrchestrationChain,
+  // Item 3: Token Budget Governance
+  validateTokenConsumption,
+  // Item 4: Consent Version Chain
+  validateConsentRecordBody,
+  validateConsentRecord,
+  // Item 7: Signed PIP Response
+  validatePipResponseBody,
+  validatePipResponse,
+} from './validate.js'

package/src/oid.ts

@@ -0,0 +1,71 @@
+/**
+ * oid.ts -- OID computation for GAP CDROs.
+ *
+ * Implements RFC 8785 JCS canonical JSON. See IMPLEMENTING.md §2.2 for the
+ * normative rules.
+ *
+ *     sha256(canonicalize(envelope_minus_excluded_fields))
+ *
+ * Excluded fields (stripped before hashing): oid, gap_version, signature,
+ * signature_key_id, supersedes. Signatures are added after OID computation.
+ *
+ * The shape passed in is the OID payload: `{ type, tenant_id, created_at_ms,
+ * created_by, body }`. The full envelope (with oid + gap_version) is built
+ * around it.
+ */
+
+import { sha256 } from '@noble/hashes/sha256'
+import { canonicalize } from './canonicalize.js'
+
+/** Convert a Uint8Array to a lowercase hex string. */
+function bytesToHex(bytes: Uint8Array): string {
+  const hex: string[] = []
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i] as number
+    hex.push((b >>> 4).toString(16))
+    hex.push((b & 0x0f).toString(16))
+  }
+  return hex.join('')
+}
+
+/**
+ * Fields excluded from the OID hash. These are present in the full envelope
+ * but MUST NOT contribute to the content hash. Strip them before hashing so
+ * that TypeScript and Python produce byte-identical OIDs regardless of whether
+ * the caller passes a pre-stripped payload or a full envelope.
+ */
+const EXCLUDED_FIELDS = new Set([
+  'oid',
+  'gap_version',
+  'signature',
+  'signature_key_id',
+  'supersedes',
+])
+
+/**
+ * Compute the OID of a GAP CDRO payload.
+ *
+ * Accepts either a pre-stripped payload or a full envelope (with oid,
+ * gap_version, signature, signature_key_id, supersedes present). The 5
+ * excluded fields are stripped before canonicalization so both forms produce
+ * the same OID.
+ *
+ * @param body - the OID payload or full envelope (see CDRO §2.1 in GAP_SPEC).
+ * @returns the canonical OID string `"sha256:<hex>"`.
+ */
+export function computeGapOid(body: unknown): string {
+  let stripped: unknown = body
+  if (body !== null && typeof body === 'object' && !Array.isArray(body)) {
+    const obj = body as Record<string, unknown>
+    const result: Record<string, unknown> = {}
+    for (const key of Object.keys(obj)) {
+      if (!EXCLUDED_FIELDS.has(key)) {
+        result[key] = obj[key]
+      }
+    }
+    stripped = result
+  }
+  const canonical = canonicalize(stripped)
+  const digest = sha256(new TextEncoder().encode(canonical))
+  return 'sha256:' + bytesToHex(digest)
+}