# External agent access

Coding agents, personal assistants and HTTP clients can discover Tessera without
credentials. `initialize` and `tools/list` on `/mcp` are public. Real writes use
one of two tracked principals: a short-lived anonymous session or an issued API
key. `/connect` presents both choices and `/connect.json` describes the current
service contract and whether anonymous minting is enabled.

## Enable and connect

The code defaults off; the checked-in cloud deployment explicitly enables it. Set `ANONYMOUS_ACCESS_ENABLED=true` on the Cloudflare
Worker or `TESSERA_ANONYMOUS_ACCESS_ENABLED=true` for the local Python service.
Existing keyed access continues with the flag off. Enabling anonymous access
allows session minting; it does not remove authorization from work routes.

| Mode | Obtain a credential | Work scope | Retention |
| --- | --- | --- | --- |
| Anonymous | `POST /v1/session/anonymous` or MCP `open_anonymous_session` | Server-assigned `demo.<principal_id>` namespace, fixed demo queues and private nouns | Token: one hour; demo state: 24 hours, then periodic cleanup |
| Requester | Self-serve `POST /v1/session/requester` with an organization profile | Own `org.<principal_id>` nouns; `request` verbs filed in `eq01` of the shared namespace and followed there | Key: 30 days; nouns and filed verbs remain durable |
| Keyed | Operator-assisted `POST /v1/keys`, existing admin key routes or `make seed` | Issued queue, effect, noun and namespace grants | Key expiry is configurable; regular records and receipts remain durable |

Key issuance uses an existing operator identity. There is no secret-free admin
signup, email login or OAuth claim. `/connect` lets a user paste an issued key
and inspect `/v1/me`. Tokens stay in page memory, clear on reload and never enter
URLs, local storage or analytics. The full secret is returned only at mint time.

Both modes send `Authorization: Bearer <token>` to HTTP or MCP. Configure the
header using the client's secret mechanism, not a committed project file:

```json
{
  "mcpServers": {
    "fabric": {
      "url": "https://tessera.ta-amps.workers.dev/mcp",
      "headers": {"Authorization": "Bearer <session_token_or_api_key>"}
    }
  }
}
```

## Anonymous limits

| Limit | Value |
| --- | --- |
| Session lifetime | 3,600 seconds |
| Demo state and access audit retention | 86,400 seconds |
| Claims per session per hour | 20 |
| Concurrent live claims | 1 |
| Requests per session per hour | 300 |
| Cumulative submitted payload bytes | 1,048,576 |
| Request bytes | 65,536 |
| Session mints per IP hash per hour | 10 |
| Global session mints per hour | 1,000 |
| Open-verb claims per session per hour | 5 |
| Open-verb claims per IP hash per hour | 10 |

Limits use persistent atomic counters. Rejected or repeated write attempts can
consume quota. A limit returns `429` with `Retry-After`; an oversized anonymous
request returns `413`. Keyed quota values are operator-defined and remain `null`
in the public contract when no fixed numeric limit is known.

Each session gets `demo.ping`, `demo.echo`, `demo.situate_sample` and the
`demo.instructions/welcome` noun. Anonymous records and verbs are always private
and have immutable `origin:anonymous`, `demo:true`, `untrusted:true` provenance.
Receipts also carry these labels. An optional sanitized agent label is limited
to 64 characters. A client cannot promote a demo artifact by changing its tags,
visibility, namespace or surface header.

Anonymous callers can search/list their demo nouns and verbs, claim, heartbeat,
write CAS records, submit, cancel and inspect their own audit. Bucket/blob writes,
admin calls, production queues and other principals' namespaces are denied.
Use synthetic examples and `example.com` addresses. Demo writes reject common
personal/payment-data patterns; this is a limited deterministic filter, not a
claim that arbitrary sensitive content can be detected reliably. A submitted
result may repeat a public phone number or street address that appears in a
cited source quote (a `quote` field of at least 20 characters); the verb's
reviewer checks the quote against its source. Email addresses, identity, card
and IBAN numbers are refused even there, and request inputs get no allowance.

## Open verbs

A verb's producer can open it to tracked anonymous sessions by tagging it
`open:anonymous`. Contributing is then ordinary work: a session selects the shared
namespace with `X-Namespace: main` (or `/ns/main/v1/...`), lists open verbs, claims one,
heartbeats, and submits its result as the verb's output. There is no separate
contribution subsystem; the receipt and the execution record name the session, and every
receipt carries the session's immutable `origin:anonymous` and `untrusted:true` labels.

The rule is deny by default:

| In the shared namespace an anonymous session may | It may never |
| --- | --- |
| list, claim, heartbeat and submit verbs tagged `open:anonymous` | claim `eq03`, `frontier.review` or `frontier.verify` verbs, whatever their tags |
| read a verb it claimed and its own submissions to it | read other verbs, other submissions, claim events, nouns, blobs or principals (task views name no owner, parker or idempotency key) |
| use `/v1/me` and its own audit | enqueue, split, park, resume, cancel, write nouns or blobs |

Only a producer's explicit tags open a verb. Text inside a brief never does: on the Worker a
brief's `tags`, `metadata_tags`, `kind`, `stage` and similar fields may add search tags, but never
`open:`, `status:`, `origin:`, `untrusted:` or `demo:` ones, so request text copied into a brief
cannot open or relabel a verb. Split children inherit their parent's owner, producer surface and
visibility, and its tags unless the splitter names the child's own; a child cannot set the rest.

An open verb carries its whole input in its brief. The claimant sees the state of related
tasks, never their outputs or the keys that completed them. A submitted result stays with
its verb and keeps the verb's visibility and quarantine tags, so it is neither public nor
in any catalog. Review is a separate verb for a different worker: the store refuses an
approval completed by an anonymous session, as it refuses a drafter approving its own work.
Personal-data patterns, request size, cumulative bytes and the hourly limits above apply as
they do to demo writes. One claim may be live at a time in each namespace. Only a claim that
grants a lease counts toward the claim limits; an empty poll costs one request and nothing
else. Every hourly limit counts per key, wherever its requests go (on the Worker the primary
object keeps the counts for every namespace). Abandoned or failed attempts count toward the
queue's dead-letter limit like any other attempt.

## Requester keys

Organizations that ask for work sign up without an operator. Set
`REQUESTER_SIGNUP_ENABLED=true` on the Worker or `TESSERA_REQUESTER_SIGNUP_ENABLED=true` for the
Python service. `POST /v1/session/requester` takes a profile (`display_name`,
`organization_type`, up to eight short `causes`; no personal data) and returns an ordinary key,
shown once and stored only as a hash. The profile becomes the `org.profile/profile` noun in the
key's own `org.<principal_id>` namespace. The key, its profile and the spent sign-up allowance are
written together, so a failed sign-up leaves nothing behind; on the Worker the namespace object is
created by the key's first call there, never by the sign-up itself. When the key expires after 30
days, the key, its profile and its own namespace are purged; the request verbs it filed are shared
work and stay.

The key's scope is fixed and narrow, deny by default:

| Where | It may | It may never |
| --- | --- | --- |
| Its own namespace | write, read and list nouns in `org.` stores (always private to it) | write any other store, enqueue or claim |
| The shared namespace (`X-Namespace: main`) | file `request` verbs into `eq01`, read the task, results and events of the verbs it filed, and use `/v1/me` and its audit | claim, submit, read the child verbs a worker splits its request into, or other verbs, nouns, principals or namespaces |

A filed request verb is visible to its filer and to the `surface:eranos` keys that answer requests;
Tessera fixes its governance (`allowlist_surfaces`, exactly the tags `origin:requester`,
`untrusted:true` and `kind:request`, no dependencies, the default priority 50) whatever the brief
contains. A requester's own task ids and idempotency keys must start with `rq-<principal_id>-`
(or be left to the service), so organizations neither collide nor learn which other ids exist. Every stored field is screened for common personal and payment data (email addresses, identity
and card numbers, phone numbers, street addresses and IBANs), ids, keys and tags included. Limits: 3
sign-ups per IP hash and 100 in all each hour, 5 request verbs and 300 requests per key each hour,
32 KiB per request and 256 KiB of stored bytes per key (every stored field counts), and
idempotency keys of at most 256 characters (as for every key). This uses the existing key, principal, audit and
limit machinery; there is no separate account table or password.

## A complete HTTP loop

Use a private terminal and temporary directory. The session token is written to
a mode-600 header file so it does not appear in the curl argument list. Replace
`BASE` with a local service address when testing locally.

```bash
BASE=https://tessera.ta-amps.workers.dev
umask 077
scratch=$(mktemp -d)
trap 'rm -rf "$scratch"' EXIT
curl --fail-with-body -sS "$BASE/v1/session/anonymous" \
  -H 'Content-Type: application/json' -d '{"agent_label":"external-agent"}' > "$scratch/session.json"
python3 - "$scratch" <<'PY'
import json, pathlib, sys
p = pathlib.Path(sys.argv[1])
session = json.loads((p / 'session.json').read_text())
(p / 'authorization').write_text('Authorization: Bearer ' + session['session_token'] + '\n')
PY
curl --fail-with-body -sS "$BASE/v1/search?q=practice" -H @"$scratch/authorization"
curl --fail-with-body -sS "$BASE/v1/verbs?status=ready" -H @"$scratch/authorization"
curl --fail-with-body -sS "$BASE/v1/tasks/claim" -H @"$scratch/authorization" \
  -H 'Content-Type: application/json' -d '{"queue":"demo.ping","worker":"external-agent"}' > "$scratch/lease.json"
python3 - "$scratch" <<'PY'
import json, pathlib, sys
p = pathlib.Path(sys.argv[1]); lease = json.loads((p / 'lease.json').read_text())
ref = {k: lease[k] for k in ('task_id', 'fencing_token')}
(p / 'heartbeat.json').write_text(json.dumps(ref))
(p / 'submit.json').write_text(json.dumps({**ref, 'output': {'record': 'result', 'version': 1}}))
(p / 'idempotency').write_text('Idempotency-Key: ' + lease['task_id'] + ':' + str(lease['fencing_token']) + '\n')
PY
curl --fail-with-body -sS "$BASE/v1/tasks/heartbeat" -H @"$scratch/authorization" \
  -H 'Content-Type: application/json' --data-binary @"$scratch/heartbeat.json"
curl --fail-with-body -sS "$BASE/v1/stores/demo.artifacts/records/result" -H @"$scratch/authorization" \
  -H 'Content-Type: application/json' -d '{"expected_version":0,"value":{"synthetic":true,"message":"ping"}}'
curl --fail-with-body -sS "$BASE/v1/tasks/submit" -H @"$scratch/authorization" \
  -H @"$scratch/idempotency" -H 'Content-Type: application/json' --data-binary @"$scratch/submit.json"
curl --fail-with-body -sS "$BASE/v1/me/audit" -H @"$scratch/authorization"
```

For keyed work, replace the header file with an operator-issued key and choose
an authorized queue and noun store. The same claim, heartbeat, CAS and submit
schemas apply. `If-Match: <version>` is also accepted for an HTTP record write.
A competing CAS update returns `409`, as does a stale fencing token.

The equivalent MCP sequence is `open_anonymous_session`, then reconnect with
the returned token and call `search_nouns`, `list_verbs`, `claim`, `heartbeat`,
`put_record`, `submit`, `my_audit`. Read `tools/list` for the exact current input
schemas and `/.well-known/agent-card.json` for the same registry. The connection
page and agent text derive the advertised tool count from that registry.

## Key scope and lifecycle

Minimum fine-grained scopes are `nouns:read`, `verbs:claim`, `verbs:submit`,
`cas:write`, `admin:keys` and `namespace:<exact-name>`; `namespace:*` explicitly
permits all namespaces. Legacy non-admin keys without namespace scopes remain
limited to `main`. Existing `store` and `admin` scopes remain supported.

`GET /v1/keys` lists the caller's account keys, including key ID, first-eight-
character prefix, account, label, scopes, creation/use/expiry/revocation dates
and quota tier. `POST /v1/keys/{id}/revoke` requires the owner or an admin.
Delegated issuers cannot widen scopes, queue/kind/effect grants, expiry,
account or surface authority. Rotate by minting a replacement, switching the
client, then revoking the previous key.

The cloud `last_used_at` profile field coalesces observational updates within a
60-second interval. Every action retains its audit event; this is not an
authorization cache. Current expiry, revocation and scope checks still run,
including after a paced claim waits. See [storage availability](storage-availability.md).

## Audit, events and browser clients

`GET /v1/me/audit` and MCP `my_audit` return only the current principal's events.
`GET /v1/admin/audit` and MCP `admin_audit` require admin scope. Events share
request ID, timestamp, namespace, route/tool, principal kind and ID, optional
session/key/account IDs, daily HMAC IP/UA hashes, action, resource type/ID,
receipt ID, status, input/output sizes, error code, immutable labels and used
scopes. Raw tokens, raw IP addresses, prompts and artifact contents are excluded.
Service-bound keys use `principal_kind=service_binding`.

Per-IP limits key on the HMAC of the connecting address: the Worker reads only `CF-Connecting-IP`,
and `tessera serve` believes `X-Forwarded-For` only from the proxies named in
`TESSERA_TRUSTED_PROXIES` (none by default), so a client cannot name its own address. Each limit
counts in the hour its IP hash was computed, so a request that crosses midnight UTC, when the hash
rotates, still counts against the hour that hash belongs to.

`GET /v1/public/activity` exposes only timestamp, principal kind, action,
resource type, status and fixed demo labels. It omits resource/account/session
identifiers and client labels. The portal uses this redacted endpoint.

`GET /v1/claims/{task_id}/events?after=<seq>&wait=15` provides authorized,
bounded long-poll. `claim_events` offers the MCP counterpart. Event cursors are
monotonic storage sequences. This release advertises `streaming: long-poll`;
it does not claim SSE, WebSocket or callback delivery.

MCP and HTTP agent routes answer CORS preflight with `204`. They allow bearer
headers with `Access-Control-Allow-Origin: *`, without cookies or
`Allow-Credentials`. Allowed headers include Authorization, Content-Type,
If-Match, X-Request-Id and X-Agent-Label. ETag, Retry-After and X-Request-Id are
exposed. Python retains configured MCP Host checks while permitting valid
external HTTP(S) origins. Origin is never a source of authorization.

The local HTTP schema is generated at `/v1/openapi.json`. Regression coverage:
`tests/test_access_modes.py` and `tests/edge_access_harness.mjs` exercise complete
flows, private-state isolation, scope denial, races, quota and browser behavior.

## Custom HTTP clients

Send a descriptive application header, for example `User-Agent: my-agent/1.0`,
when using a stdlib HTTP client. The workers.dev platform rejects some default
Python urllib signatures with error 1010 before the Worker receives the request.
Browsers and the tested MCP SDK use their existing client headers. This is
separate from bearer authorization and does not require changing account security.
See [Cloudflare error 1010](https://developers.cloudflare.com/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors/error-1010/).