@forge-os/aegis

W3C Verifiable Credentials SDK for ArtefactForge OS.

Adoption guide: docs/aegis-sdk-adoption-2026-05-18.md — three end-to-end use cases (browser verify, sign-policy worker, audit fingerprint) with the polyfill recipe required for browser/edge runtimes today.

Aegis is the trust layer of forge-os: every meaningful agent decision can be issued as a W3C Verifiable Credential signed with Ed25519, anchored in a hash-chained audit table, and verified by anyone — including auditors and regulators with no access to the OS backend.

What this package is

A verification-only SDK for the canonical Aegis trust layer. Use it when you need to:

• Validate a VC issued by ArtefactForge OS (verifyVc)
• Decide whether a decision requires signing (evaluateSignPolicy, requiresSign, getSignCostThreshold)
• Compute audit fingerprints (hashJson, hashString)
• Work with low-level Ed25519 primitives (generateKeyPair, signMessage, verifySignature) for your own DIDs

Everything in the recommended import surface below is pure — no DB calls, no env variables required at runtime — so it works in browsers, edge runtimes, auditing tools, and offline scripts.

What this package is NOT (anymore)

Per ADR-036 (2026-05-06), the signing path for did:key:z6Mk85GCp9YIGEqeQhYKUJecqylr54fzj4DlyJsV83Ui (the canonical BOSS issuer) lives exclusively in the aegis-signer Supabase Edge Function. The keypair is held in Supabase Vault and is never exposed to any worker or client process.

Functions that perform signing or DB writes against forge_aegis.* — issueVc, appendAuditChain, getOrCreateDid, getPrivateKeyFromEnv — are kept exported for backwards compatibility and for users running their own Aegis instance, but the canonical forge-os runtime does NOT use them. The llm-direct-worker calls the Edge Function over HTTP (see packages/llm-direct-worker/src/aegis-client.ts).

Recommended import surface

import {
  // Verification (the SDK use case)
  verifyVc,
  type VerifyVcResult,
  type AegisVerifiableCredential,
  type DidDocument,

  // Sign policy (worker decides whether to call the Edge Function)
  evaluateSignPolicy,
  requiresSign,
  getSignCostThreshold,
  type SignPolicyInput,
  type SignPolicyResult,

  // Audit fingerprinting
  hashJson,
  hashString,

  // Low-level Ed25519 (for advanced consumers running their own DIDs)
  generateKeyPair,
  signMessage,
  verifySignature,
  toBase64Url,
  toMultibase,
  fromMultibase,
} from '@forge-os/aegis';

Verification example

import { verifyVc } from '@forge-os/aegis';

// Fetch the credential and the issuer DID Document from wherever they live.
// They are public artefacts — no Supabase access required.
const credential = JSON.parse(vcJsonString);
const didDoc = await fetch(`https://forge.example/dids/${credential.issuer}`)
  .then(r => r.json());

const result = verifyVc(credential, didDoc);
if (result.valid) {
  console.log('VC verified for', credential.credentialSubject.decision_kind);
} else {
  console.error('VC invalid:', result.reason);
}

verifyVc() re-canonicalises the credential without the proof, decodes the Ed25519VerificationKey2020 from the DID Document, and runs an Ed25519 signature check. Returns { valid: boolean, reason?: string } — no exceptions on bad input.

Sign policy example

The policy is a deterministic, pure function. Its output is the canonical trigger for the worker to decide whether to call aegis-signer:

import { evaluateSignPolicy } from '@forge-os/aegis';

const policy = evaluateSignPolicy({
  risk_level: 'high',
  cost_usd: 2.5,
  is_irreversible: true,
});

if (policy.required) {
  // Worker code POSTs to aegis-signer Edge Function here.
  // Reason is stored on the VC subject for audit trail.
  console.log('signing required:', policy.reason);
}

Policy rules (first match wins):

| Order | Trigger | reason | |---|---|---| | 1 | explicit_user_request === true | explicit_user_request | | 2 | is_irreversible === true | external_action_irreversible | | 3 | risk_level === 'critical' | risk_level_critical | | 4 | risk_level === 'high' | risk_level_high | | 5 | cost_usd > AEGIS_SIGN_COST_THRESHOLD_USD (default 1.0) | cost_above_threshold_<value>_usd | | else | — | below_all_thresholds |

Audit chain

The hash-chained audit trail lives in the SQL table forge_aegis.audit_chain inside the forge-os Supabase project. Each row contains prev_hash and hash columns computed by an SQL trigger on insert, so the chain is tamper-evident at the database layer and verifiable end-to-end via the RPC aegis_chain_verify.

This package does not read the chain — fetch it via Supabase RPC (or the aegis-signer Edge Function endpoints /verify, /tail, /stats). The verification of individual VCs against their issuer DID Document is what this SDK provides.

Compatibility note for existing consumers

If your code currently imports issueVc or getOrCreateDid from this package and signs against forge_aegis.* directly, you have two options:

1. Migrate to the Edge Function (recommended): import AegisSignerClient from @forge-os/llm-direct-worker (or roll your own HTTP client) and call the canonical signer.
2. Stay on local signing (only if you run a separate Aegis instance with its own DID): functions remain exported. Be aware that any VC you produce will not chain into the canonical forge_aegis.audit_chain of forge-os.

License

Elastic License 2.0 — see LICENSE at the repo root.