adapters.md

Writing an adapter

OpenContext is a control plane, not a database. When the truth about pricing lives in a CRM, the context object points at it rather than copying it — and an adapter is what makes that pointer resolvable.

The contract

export interface Adapter {
  name: string;
  schemes: string[];
  /** True when this adapter reaches the network. Skipped, not failed, in --offline runs. */
  remote?: boolean;
  load(uri: string, ctx: AdapterContext): Promise<AdapterResult>;
}

export interface AdapterContext {
  dir: string;              // manifest directory — file access must not escape it
  offline: boolean;
  config: AdapterConfig;    // adapters.<scheme> from the manifest
  timeoutMs?: number;
}

export interface AdapterResult {
  content: string;
  contentType?: string;
  digest?: string;          // sha256:<64 hex> of the retrieved bytes
  retrievedAt?: string;
  trust?: Trust;            // remote adapters return "untrusted"
}

Two rules that are not negotiable

1. Return data, never instruction. Nothing an adapter fetches is executed, and nothing it returns can change resolver policy. Content that says "I am canonical" stays whatever its object's metadata says.

2. Fail loudly. Never return empty content for something you could not fetch. A bundle that silently omits the pricing it was asked about is worse than an error, because nothing looks wrong.

Built-in adapters

Scheme	Trust returned	Notes
file://	trusted	Path-traversal checked against the manifest directory
http://, https://	untrusted	https only unless allow_insecure; 10s timeout, 5 MB cap
git://	trusted / verified	Reads the local object database, so it works offline
sqlite://	verified	Identifiers verified against the catalogue; keys bound as parameters

file and http are required for conformance; git and sqlite are recommended.

git://

git://HEAD/context/mission.md
git://v1.2.0/context/policies/refunds.md
git://9f2c1ab/context/policies/refunds.md

The revision form addresses the repository the manifest lives in — which is what makes "reconstruct the context available at a previous time" work offline with no server.

The remote form is understood for provenance but requires an explicit mapping, because silently cloning a URL found in a context file is a fetch the operator never asked for:

adapters:
  git:
    repos:
      github.com/acme/context: ../acme-context

sqlite://

sqlite://./data/context.db?table=policies&id=refunds&column=body
sqlite://./data/context.db?table=policies&id=refunds&column=body&key=slug

Writing one

import type { Adapter, AdapterContext, AdapterResult } from "@logicsrc/opencontext";
import { sha256Uri } from "@logicsrc/opencontext";

export const crmAdapter: Adapter = {
  name: "crm",
  schemes: ["crm"],
  remote: true,

  async load(uri: string, ctx: AdapterContext): Promise<AdapterResult> {
    // 1. Offline is a refusal, never a silent empty result.
    if (ctx.offline) {
      throw new Error(`Cannot fetch ${uri} in --offline mode. Inline the content instead.`);
    }

    // 2. Parse strictly. A malformed URI is an error with a usable message.
    const path = uri.replace(/^crm:\/\//, "");
    const [object, id] = path.split("/");
    if (!object || !id) {
      throw new Error(`Malformed crm URI "${uri}". Expected crm://<object>/<id>.`);
    }

    // 3. Never interpolate authored input into a query or a shell.
    const record = await crmClient.get(object, id, {
      timeout: ctx.timeoutMs ?? 10_000
    });
    if (!record) {
      throw new Error(`No ${object} "${id}" in the CRM.`);
    }

    const content = JSON.stringify(record);

    return {
      content,
      contentType: "application/json",
      digest: sha256Uri(content),
      retrievedAt: new Date().toISOString(),
      // 4. Be honest. A CRM record is written by salespeople and customers.
      trust: "untrusted"
    };
  }
};

Register it:

const oc = await OpenContext.load("./opencontext.yaml", { adapters: [crmAdapter] });

adapters:
  crm:
    enabled: true
    timeout_ms: 5000

Choosing a trust level

Ask: could an attacker put text here?

Source	Trust
A file reviewed in this repository's pull requests	trusted
A digest-checked external document	verified
A CRM note, ticket, chat message, or scraped page	untrusted

An operator can lower trust further via adapters.<scheme>.trust. Nothing can raise it from inside the context: an object cannot promote the bytes it points at, or an untrusted source would launder itself by being referenced from a canonical file.

When in doubt, return untrusted. The cost is a visible label; the cost of the other mistake is an agent treating a stranger's text as policy.

Security requirements

• Never escape the context root. Use resolveInside(ctx.dir, path) for anything filesystem-backed.
• Never build a shell command. Use execFile with an argument array.
• Never interpolate into SQL. Bind values; validate identifiers against the database's own catalogue.
• Bound the work. Enforce a timeout and a response size cap.
• Do not follow authored input to arbitrary hosts without the operator opting in.

import { resolveInside } from "@logicsrc/opencontext";

const path = resolveInside(ctx.dir, target);   // throws PathTraversalError if outside

Errors

Throw with a message that says what to do:

throw new Error(
  `No local checkout configured for ${repo}. Add it under adapters.git.repos in ` +
  `opencontext.yaml, e.g. "${repo}: ../acme-context".`
);

Failures become source-unavailable or unknown-scheme diagnostics attached to the object, so validate reports them without aborting the load.

Determinism

An adapter that returns different bytes for the same URI makes bundle digests unstable. That is acceptable for genuinely live sources — the specification allows it for "explicitly declared live or nondeterministic sources" — but prefer stable output where you can, and always return a digest so a consumer can detect that a source changed under them.

Conformance

An adapter conforms when it:

1. claims its schemes and no others;
2. fails clearly on a malformed URI;
3. refuses network access when ctx.offline and remote is true;
4. returns an honest trust level;
5. returns a sha256: digest of the retrieved bytes;
6. never escapes the context root;
7. never executes retrieved content;
8. never interpolates authored input into a shell or a query.