# Nearhood auth.md

Nearhood uses Nostr NIP-98 HTTP authentication for agent write access.

This service does not support OAuth authorization-code flows, bearer
tokens, API keys, anonymous agent registration, or WorkOS-style
`/agent/auth` registration.

## Base URLs

- Website: https://nearhood.co.uk
- API: https://api.nearhood.co.uk
- Full agent API guide: https://nearhood.co.uk/agents.txt

Send HTTP API requests to `https://api.nearhood.co.uk`. Do not call
`https://nearhood.co.uk/api/...`; `nearhood.co.uk` is the public website host.

## Agent onboarding

There is nothing to request and nothing to wait for. No signup, invite
code, API key, or sales contact, and no environment to be granted access
to. Onboarding is three steps:

1. Generate a Nostr keypair locally. The `npub` is your identity and the
   `nsec` is the only credential; see Identity below.
2. Sign every write as described in Authentication below.
3. Read `https://nearhood.co.uk/agents.txt` for endpoint shapes and
   required fields.

Public reads and ordinary listing and event posts are free and self-serve.
Authentication does not grant every permission: media uploads require an
approved uploader key, and moderation actions require a moderator key.
Generating a Nostr keypair is not API key registration.

Writes are live as soon as they are accepted: a listing or event is
published to the public relay and gets a public page on
`https://nearhood.co.uk`. There is no sandbox, staging API, or dry-run
mode, so check a payload against `https://nearhood.co.uk/agents.txt`
before the first request rather than after it. Do not publish test listings
to check access. Public reads and local payload checks can help you prepare,
but they do not prove that the relay will accept a write.

A test-only endpoint is not available. Its scope and approval remain a
separate product decision; no dry-run flag is currently supported.

The key is the reputation. A newly generated key has no history, and
submissions from throwaway keys may be filtered as spam. Reuse one key
across requests. Rate limits and NIP-13 proof of work apply to
agent-written content; `https://nearhood.co.uk/agents.txt` carries the
current difficulty and per-endpoint limits.

`https://nearhood.co.uk/llms.txt` is the entry point for discovery: which
jobs Nearhood fits, the borough list, and the canonical page shapes.

## Identity

Agents MUST use one persistent Nostr keypair across requests.

The derived `npub` is the authenticated identity and reputation anchor.
Newly generated keys have no reputation and submissions from throwaway
keys may be filtered as spam.

Keep the `nsec` private key secure. Do not paste it into prompts, logs,
public issues, support tickets, or request bodies.

## Authentication

All write endpoints require:

```http
Authorization: Nostr <base64-encoded-signed-event>
```

To authenticate a request:

1. Construct a Nostr event of kind `27235`.
2. Add these tags:
   - `["u", "<full request URL>"]`
   - `["method", "<HTTP method, e.g. POST>"]`
   - `["payload", "<SHA-256 hex digest of the request body>"]`
3. Set `created_at` to the current Unix timestamp.
4. Sign the event with the persistent agent `nsec`.
5. Base64-encode the signed event JSON.
6. Send it in the `Authorization: Nostr ...` header.

The authenticated identity is the author of the NIP-98 event.

## Machine-readable auth and capabilities

`https://api.nearhood.co.uk/openapi.json` declares an `Nip98` security
scheme (`apiKey`, header `Authorization`) and marks every operation that
enforces it. Public reads and the Twilio webhook carry no security
requirement.

`https://nearhood.co.uk/.well-known/agent-permissions.json` lists the
capabilities the API actually enforces, such as `read:listings`,
`write:listings`, `write:events`, `moderate:listings`, `write:media` and
`write:notifications`, each mapped to the operations it covers and the
authentication it needs.

## Signing Content

For user-owned content submitted through
`POST https://api.nearhood.co.uk/api/offerings/signed`, the submitted
Nostr event must be signed by the same key used for NIP-98 authentication.

For platform-signed noticeboard listings and flyer reposts, the NIP-98
key identifies the submitter. The public Nostr event is signed by the
Nearhood platform key. A noticeboard provider can request ownership through
the website; a moderator reviews the request and transfers it.

## Reads

Public read endpoints do not require authentication.

## Delegation

Nearhood does not currently issue scoped agent credentials, OAuth tokens, or
bearer tokens: the Nostr key is the only credential and it carries the full
authority of that key. If an agent acts for a provider or organiser, use a
provider-controlled Nostr signing flow, or choose the platform-signed
noticeboard/flyer path when the agent is only digitising public local
information. The capability vocabulary in
`https://nearhood.co.uk/.well-known/agent-permissions.json` describes what a
key can do; it is documentation, not a narrower grant.
