Security and deployment

This page is the security contract for the Auwai knowledge service and the native harness plugins.

Assets

• Repository source and indexed metadata.
• Facts, findings, claims, read coverage, plans, and jobs.
• Knowledge-service tokens and database credentials.
• Agent instructions, prompts, and model outputs.
• Plugin hook configuration and local scripts.

Trust boundaries

1. The developer and the agent run on the same machine or trust boundary.
2. The harness invokes the plugin, MCP server, or CLI.
3. The knowledge service receives HTTP requests from agents.
4. The storage adapter reaches a local SQLite file or a network database.
5. A reverse proxy terminates TLS for a non-loopback service.

The local ledger is inside the developer trust boundary. The knowledge service is a separate boundary and needs authentication, repository scopes, request limits, and TLS when it leaves loopback.

Threat model

Redaction is best effort. Do not put secrets in source, fixtures, findings, or prompts. A token that can write facts or claims is a trusted team credential.

Deployment checklist

• Bind the service to 127.0.0.1 by default.
• Put it behind a TLS reverse proxy for any non-loopback bind.
• Use a dedicated service user and a least-privilege database user.
• Set AUWAI_KNOWLEDGE_TOKEN from a secret store, not a shell history.
• Use an auth file with per-repository scopes for more than one team.
• Set --backlog to at least 128 for concurrent agents.
• Set --max-body-bytes to the smallest reasonable limit.
• Back up the database and test the restore path.
• Keep .auwai and database files out of version control.
• Do not expose the service directly to the public internet.
• Do not use --allow-anonymous-network outside a trusted proxy boundary.

Token scopes

The service accepts a static token or an auth file:

{
  "tokens": {
    "token-a": {
      "principal": "team-a",
      "repos": ["github.com/acme/telemetry"],
      "scopes": ["read", "write"]
    }
  }
}

read allows facts and coverage; write allows sync, findings, claims, and plans; jobs allows full-read job operations. Use * only for a trusted single-team deployment.

TLS example

Terminate TLS at a reverse proxy and forward to loopback:

server {
    listen 443 ssl;
    server_name auwai.internal.example;

    ssl_certificate     /etc/ssl/auwai/fullchain.pem;
    ssl_certificate_key /etc/ssl/auwai/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8765;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

The release sign-off, residual risks, and test evidence are in security-signoff.md.

Security verification

Before a release:

• Run the authentication, scope, redaction, request-limit, and malformed-payload tests on SQLite, PostgreSQL, MySQL, and MariaDB.
• Verify an anonymous service refuses a non-loopback bind without the explicit override.
• Verify a token with only read cannot sync facts, findings, or claims.
• Verify a token for repository A cannot read repository B.
• Verify a secret in a fact, finding, and claim is redacted.
• Verify the reverse-proxy example with a disposable certificate.
• Record residual risks and assign an owner for each medium finding.

Known limits

• There is no built-in OIDC or user directory. Put OIDC at the reverse proxy or use static scoped tokens.
• Redaction is a filter, not a guarantee.
• The service is not a code-execution sandbox. Treat agents as trusted local users unless the harness isolates them.
• The default SQLite backend is single-threaded. Use PostgreSQL for multiple service processes and HA.