Antfly Authorization
This document describes Antfly's data-plane authorization model: what is implemented today, then the design for join-aware enforcement that is still planned. The model is provider-neutral: Antfly can receive principal context from its built-in user manager, a trusted gateway, a managed control plane, or a self-hosted deployment.
Secure Deployment
Local quickstarts disable authentication and bind to loopback. Docker examples
keep the application listening on 0.0.0.0 inside the container but publish
host ports on 127.0.0.1. Do not remove that host binding until you have
configured authentication and TLS termination at a trusted reverse proxy.
Metrics and auxiliary development services should also remain private.
To enable built-in authentication, use --auth true or "enable_auth": true
in the config file. On first startup, supply a unique administrator password
through ANTFLY_BOOTSTRAP_ADMIN_PASSWORD (12 to 72 bytes). For example:
export ANTFLY_BOOTSTRAP_ADMIN_PASSWORD="$(openssl rand -base64 24)"
# Save the generated password securely before removing the environment variable.
antfly standalone --auth true
For Docker, forward the variable without putting its value in command arguments:
docker run -p 127.0.0.1:8080:8080 \
--env ANTFLY_BOOTSTRAP_ADMIN_PASSWORD \
-v antfly-data:/antflydb \
ghcr.io/antflydb/antfly:latest \
standalone --host 0.0.0.0 --data-dir /antflydb --auth true
The administrator username is admin. The password is stored as a hash;
Antfly never logs it. The bootstrap variable can be removed after successful
initialization. Subsequent startups preserve an existing non-default password,
even if the variable changes; use the authenticated user-management API to
rotate credentials. Configure each node's local auth store as appropriate for
your distributed deployment; bootstrap is not a cluster-wide password update.
Upgrade from legacy defaults: an auth-enabled instance with the old
admin:admin credential refuses to start without a valid bootstrap password.
Supplying the variable replaces that known default while preserving permissions.
HA primary and standby startup never rewrites credentials from a portable seed;
rotate legacy credentials before capturing a replacement HA seed.
Built-in authentication also applies to MCP tools on /mcp/v1, served on the
same public port. A separately configured trusted-principal gateway is another
supported authentication boundary. CORS is a browser access policy, not an
authentication mechanism: enabling CORS without allowed_origins grants no
cross-origin access. Configure exact trusted origins; "*" requires explicit
opt-in and cannot be combined with credentialed CORS.
Native memory curation
Grant the shared table permission curator on a memory space's logical table
(for example memory_team). Curator includes read access and the native memory
proposal, verdict and entity curation operations. It does not include arbitrary
table writes, configuration, ontology changes, source-wide forgetting or
embedding publication. Admin includes curator; write alone does not.
Pinning a team-visible memory into the session brief also requires curator, because it changes every principal's injected context; owners pin their private memories with write.
HTTP, /memory/v1/mcp and /memory/v1/mcp/agent share this authorization. Operations retain their
required grant and recheck the live credential at publication and receipt replay.
Revocation applies to admitted work as well as new requests. Private records
remain in their owner's audience. Lite's database owner retains full rights.
Local files in remote templates
remoteText, remotePDF, remoteMedia, and other file download callers deny
file:// unless remote_content.security.allowed_paths explicitly allows
the target. Omitted and empty path lists deny local file access. To permit an
intentional ingestion directory:
{
"remote_content": {
"security": {
"allowed_paths": ["/srv/antfly/ingest"]
}
}
}
Use a dedicated directory containing only data that authorized callers may read. Canonical path checks reject sibling-prefix and symlink escapes. An allowlist grants access to readable files beneath it; authentication alone does not make arbitrary local paths appropriate template inputs. Private-IP blocking continues to protect HTTP downloads and does not authorize local files.
Current Implementation
Credentials
When auth_enabled is true, public routes authenticate through the built-in
user manager (/auth/v1) with one of:
Authorization: Basic <base64(username:password)>Authorization: ApiKey <base64(key_id:key_secret)>Authorization: Bearer <base64(key_id:key_secret)>
An API key can only narrow its owner's permissions, and that narrowing is re-applied on every use.
Trusted Principal Tokens
A gateway in front of Antfly can instead send an HS256-signed JWT in the
X-Antfly-Trusted-Principal header. Antfly verifies it with the keystore secret
antfly.trusted_principal.secret and, when antfly.trusted_principal.issuer is
set, requires a matching iss. The claims are:
{
"iss": "gateway",
"sub": "user_123",
"exp": 1790000000,
"iat": 1789996400,
"tables": ["orders", "customers"],
"operations": ["read"],
"row_filter": {
"orders": { "term": { "tenant_id": { "$auth": "metadata.tenant_id" } } },
"*": { "term": { "region": "na" } }
},
"metadata": { "tenant_id": "tenant_abc" }
}
subandexpare required; a token whoseiatis more than 60 seconds in the future is rejected.admin: truegrants admin on every table. Otherwiseoperations(read,write,admin, or*) is granted on each table intables, or on every table whentablesis absent or empty.row_filtermaps a table name, or*for every table, to a row filter.metadatasupplies the values that$authreferences resolve against.
Row Filters
Row filters are query JSON stored per table, with * applying to every
table. They are attached to users, roles, and groups through
/auth/v1/users/{user}/row-filters/{table} and
/auth/v1/subjects/{subject}/row-filters/{table}, or carried in a trusted
principal token. A filter references trusted values with $auth nodes:
{ "term": { "tenant_id": { "$auth": "metadata.tenant_id" } } }
$auth accepts username, roles (the user's inherited role and group
subjects, for array-aware operators such as terms), and metadata.<path>.
Filters are validated before they are stored.
At read time, Antfly:
- Combines every matching global (
*), namespace, and table filter withAND. Anullfilter adds no restriction; it never removes broader filters. - Combines filters from every principal with
AND: the user's own filter, the filters of every role and group the user inherits, and an API key's own filter. - Resolves
$authreferences against the authenticated identity. - Combines the result with the caller's query with
AND.
Each stored policy is limited to 16,384 policy nodes and at most 64 levels
of nesting. Antfly validates matching policies independently, so its generated
conjunction does not consume a policy's nesting allowance. The effective
conjunction is limited to 32,768 JSON values, including the generated wrapper,
before and after identity expansion. Matching policies are parsed one at a time;
composition stops at the first denied or over-budget component without building
or parsing the remaining conjunction. Temporary composition memory scales with
the bounded accepted prefix and a reusable single-component workspace, rather
than all matching policies. This bound also keeps the resulting plan within the
storage compiler's existing execution budget. Exceeding the aggregate
limit denies authorization (403); it does not make the client's query invalid.
All matching policies share a separate 16,384-value identity-expansion budget.
Missing, incompatible, or over-budget identity values deny the entire predicate.
Queries, document scans, lookups, and retrieval-agent queries apply these filters. In a join, the right table's filter is applied as well.
Goals
Antfly should enforce authorization at the data-plane boundary where queries are parsed, planned, and executed. External systems can authenticate users and resolve policies, but Antfly must make the final table, operation, and row-level decision for every request it executes.
The authorization system should support:
- Tenant or instance isolation.
- Principal identity and principal type.
- Table-level read, write, and admin permissions.
- Optional per-table row filters.
- Principal attributes for explicit policy templates.
- Cross-table queries, joins, subqueries, vector search, full-text search, and retrieval workflows.
- Fail-closed behavior when policy context is missing or invalid.
Planned: Join-Aware Enforcement
The rest of this document is the design for enforcing authorization inside the query planner, for cross-table queries such as SQL joins, subqueries, and views. It is not implemented yet. Where it differs from the current behavior above, the current behavior is what Antfly does today.
Principal Context
Requests should carry a trusted principal context. The context may be created by Antfly itself or by a trusted component in front of Antfly, but clients must not be able to forge it.
Proposed shape (the shipped token claims are listed under Trusted Principal Tokens above):
{
"principal_id": "user_123",
"principal_type": "user",
"tenant_id": "tenant_abc",
"tables": {
"orders": {
"operations": ["read"],
"row_filter": {
"field": "tenant_id",
"equals": "tenant_abc"
}
},
"customers": {
"operations": ["read"],
"row_filter": {
"field": "region",
"in": ["na", "eu"]
}
}
},
"attributes": {
"tenant_id": "tenant_abc",
"region": "na"
},
"expires_at": "2026-05-19T23:00:00Z"
}
The trusted context should include enough information for Antfly to authorize without making per-row callbacks to an external policy service.
Operations
Antfly should distinguish at least:
read: query, search, get, list, graph traversal, retrieval.write: insert, update, delete; impliesreadonly when the policy says so.admin: schema, indexes, table settings, policy metadata; implieswriteonly when the policy says so.
Authorization should be checked against the operation actually executed, not only the HTTP method or top-level API route.
Row Filters
Row filters are mandatory security predicates. They are not user preferences, default filters, or ranking hints.
Row filters should be represented as structured expressions, not raw SQL or unvalidated string snippets. A row filter can reference trusted principal attributes through explicit templates:
{
"field": "tenant_id",
"equals_principal_attribute": "tenant_id"
}
Before execution, Antfly should compile the template against:
- The target table schema.
- The trusted principal attributes.
- The supported filter operators for the target backend.
Unknown fields, missing attributes, unsupported operators, and type mismatches must fail closed.
Join-Aware Enforcement
A cross-table query is a request against every table it references. A principal with access to one table must not be able to infer restricted rows from another table by joining through an allowed table.
Antfly should enforce joins with these rules:
- Every referenced table, index, collection, view, or saved query must resolve to a table authorization node before execution.
- Each referenced table must pass the required operation check.
- Each table's row filter must be attached to that table's logical scan node.
- Filters must be bound through the table alias used in the query plan.
- User predicates and security predicates combine with
AND. - Multiple grant filters for the same table and operation combine with
ANDtoday (see Row Filters above), then the result isANDed with the caller's predicate. Whether separate grants should instead widen access withORis an open design question. - If any referenced table lacks permission, deny the entire query.
- Outer joins must filter the restricted side before join evaluation while preserving normal join semantics for rows that pass authorization.
- Subqueries, CTEs, unions, graph traversals, vector search, full-text search, and retrieval-agent requests must normalize into table access nodes with the same authorization constraints.
- Views and saved queries must either expand to their underlying table access nodes or be denied unless Antfly can prove the saved object already carries an equivalent authorization policy.
Planning Boundary
Authorization should run after parsing and before physical planning or execution.
The planning pass should:
- Extract all table references from the parsed query.
- Determine the operation required for each reference.
- Resolve table policies from the trusted principal context.
- Compile row filter expressions against table schemas.
- Bind filters to query aliases.
- Attach filters to logical scan/search nodes.
- Deny the request if any reference cannot be authorized.
This keeps enforcement inside Antfly, where the system has enough context to handle joins safely. Rewriting request bodies at a proxy or route layer is not sufficient for cross-table authorization because it cannot reliably see every logical table access.
Performance
The authorization path should be efficient enough for production query traffic.
Recommended approach:
- Compile policies once per request and attach them to the plan.
- Cache compiled policy fragments by tenant, principal or role version, table, schema version, and policy version.
- Push predicates into table scans, vector indexes, full-text indexes, and graph traversal sources.
- Avoid per-row calls to external authorization systems.
- Include policy IDs or versions in audit metadata for explainability.
V1 Implementation Checklist
For a first join-aware version:
- Define a trusted auth envelope and validation rules.
- Add table-access extraction for parsed queries.
- Add a logical authorization pass before execution planning.
- Compile the row-filter DSL into Antfly predicate nodes.
- Apply filters at scan/search/index access nodes.
- Deny scoped principals from cross-table APIs until the auth pass is active.
- Add audit metadata for principal, tenant, operation, table policies, and denied references.
Minimum tests:
- Single-table read with a table-specific row filter.
- Wildcard table grant plus table-specific narrowing.
- Two-table join where both tables have filters.
- Join denied when one table lacks access.
- Aliased join where filters bind to the correct aliases.
- Nested subquery or CTE where inner table filters still apply.
- Outer join where restricted-side filters are applied before join output.
- Vector and full-text searches receive the same table row filters.
- Caller-supplied filters cannot override security predicates.
- Missing principal attributes fail closed.