Local API

Note

Specification: draft. The Unix daemon implements JSON-RPC evaluation, policy validation, and operator approval methods; shiin-client exposes evaluation and policy validation. Windows named pipes and attested agent identity remain unimplemented.

Version: shiin.local-api/v1-draft.2.

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals.

The local API lets custom agents and integrations ask Shiin for decisions (ADR-0023, ADR-0024).

Transport

[API-001] The local API MUST run over a Unix domain socket on Linux and macOS, and a Windows named pipe on Windows.

[API-002] The transport MUST be local-only and MUST NOT accept connections from remote hosts.

Protocol

[API-003] The protocol MUST be JSON-RPC 2.0.

[API-004] The methods are:

[API-007] Evaluation methods MUST carry an action request as params. Policy validation MUST carry source (the policy text) and workspace (the workspace root) as string fields in params.

Authentication

[API-005] The caller’s identity MUST be established at the attested-local assurance level or higher. The current service verifies that Unix peers share the daemon user’s UID but does not yet bind that credential to the request’s agent identity.

Failure

[API-006] Any error, timeout, or unreachable daemon MUST produce a fail-closed deny. shiin-client returns an error; callers MUST stop the requested action unless the decision is allow.

Example

{
  "jsonrpc": "2.0",
  "id": "0190f3a0-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
  "method": "shiin.evaluate",
  "params": {
    "schema": "shiin.action-request/v1-draft.1",
    "id": "0190f3a0-1c2d-4e3f-8a4b-5c6d7e8f9a0c",
    "session": "sess-001",
    "agent": { "id": "agent-001", "assurance": "asserted" },
    "action_type": "fs.read",
    "effects": [
      { "kind": "path", "value": "/home/dev/project/src/login.rs", "confidence": "exact" }
    ],
    "task": null,
    "policy_snapshot": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
    "host": { "name": "custom-agent" },
    "workspace": { "root": "/home/dev/project" }
  }
}

{
  "jsonrpc": "2.0",
  "id": "EXAMPLE-policy-validation",
  "method": "shiin.policy.validate",
  "params": {
    "source": "version = 1\n[defaults]\ndecision = 'deny'\n",
    "workspace": "/home/dev/project"
  }
}

Revision history

• v1-draft.2 (2026-10-16): Bind evaluation and policy-validation parameters to their schemas; the Rust client uses the daemon’s source field and rejects unsupported decision versions.
• v1-draft.1 (2026-10-01): Initial draft.
• Implementation update (2026-10-16): Documented the existing Unix daemon methods and Rust client. Windows transport and identity binding remain open.