@aopslabs/host-auth

Principal-authority providers for AOPS Labs plugin hosts.

Trusted-local authority is loopback-only by default. Hosts may attach an explicit, bounded role/capability list to the local operator; wildcard and malformed authority values are rejected during provider construction. The caller address must come from the server adapter rather than forwarded client headers. The trusted-local tenant is also host-configured; an x-tenant-id header cannot replace it.

Installation

```bash npm install @aopslabs/host-auth ```

The public surface provides trusted-local development authority and a production South `/api/auth/authority-projection` oracle. South credentials are forwarded narrowly, Auth and verified South tenant identities remain distinct, and bounded token-hash/authority caches expose only statistics and explicit invalidation.

`authorityMode: 'projection-v1'` is the default. The legacy `'auth-me-compat'` mode must be selected explicitly, never probes or silently falls back, and is not production-grade South tenant proof.

Application-bound authority is an explicit opt-in:

Use the application slug and resource audience registered in South; names are not a fixed product list. The retired integrationKey configuration option is rejected even when empty or combined with a slug. Human v2 requests send only x-south-application and x-south-audience; South rejects the presence of the retired x-south-integration header. Service authority uses the same explicit slug/audience expectations without forwarding caller authority selectors. Human and service authority responses and host contexts omit profile metadata; the former SouthIntegrationKey output type is no longer exported. Registered application/resource identities, audiences and current grants remain authoritative.

```ts createSouthOracleAuthorityProvider({ baseUrl: 'https://south.example.com', authorityMode: 'projection-v2', applicationSlug: 'meridian-storefront', audience: 'urn:meridian:catalog', }) ```

Both application and audience are mandatory in v2 and invalid in the other modes, preventing an incomplete configuration from silently using v1. The provider calls only `/api/auth/authority-projection/v2`, verifies the exact tenant/application/client/resource/authorization-space boundary, rejects wildcards, and forwards or creates a correlation id surfaced on the returned request context. Its positive cache key is the bearer hash plus tenant, application, and audience; its TTL is bounded by the token, session, grant-neutral application-session binding, South revalidation hint, and 60 seconds. The verified expiry and revalidation bounds are carried on the returned request context. Only 401/403 decisions are negative-cached, for at most 10 seconds; malformed responses and outages fail closed and are never cached.

createSouthTokenFamilyAuthorityProvider performs a no-fallback bearer-family selection: an exact south_sat_ access token reaches only the service oracle; malformed South service material and raw south_svc_ credentials are rejected locally; all other bearer forms reach only the configured human oracle. Route adapters remain responsible for rejecting cookies, PATs, and mixed credential families before invoking this provider.

License

Copyright (c) 2026 Mehmet Zeki Sönmez. Licensed under the PolyForm Strict License 1.0.0; see LICENSE.