@o3co/create-auth-policy-verifier 0.3.1 → 0.4.0

package/templates/standalone/config/application.conf

@@ -1,35 +1,331 @@
 http {
-  hostname = "0.0.0.0"
+  # Loopback by default: /verify answers with an authorization decision, so a
+  # reachable port is a decision oracle for anyone who can route to it. The
+  # deployment shape this template targets is a sidecar — the enforcement layer
+  # talks to the verifier over loopback and nothing else can.
+  #
+  # A containerised deployment must bind all interfaces to be reachable from
+  # another container: set HTTP_HOSTNAME=0.0.0.0 explicitly (docker-compose.yml
+  # does), and configure http.callerAuth below so the reachable port is not open.
+  hostname = "127.0.0.1"
   hostname = ${?HTTP_HOSTNAME}
+  # A whole number from 1 to 65535. Like every numeric setting in this file it
+  # is checked at boot, so a variable exported empty or holding something that
+  # is not a number fails here rather than binding an arbitrary free port.
   port = 3000
   port = ${?HTTP_PORT}
   pathPrefix = ""
   pathPrefix = ${?HTTP_PATH_PREFIX}
+
+  # Optional shared credential authenticating the SERVICE that calls /verify —
+  # a different question from the bearer token, which only establishes the
+  # subject a decision is about. Set HTTP_CALLER_AUTH_TOKEN and have the
+  # enforcement layer send the same value in the header below; the verifier then
+  # rejects every other caller before it does any decision work.
+  #
+  # Leaving the token unset leaves the endpoints open to anyone who can reach
+  # the port. That is supported (and is fine on loopback), but the server logs
+  # `unauthenticated_non_loopback_bind` at boot if the bind is not loopback.
+  callerAuth {
+    token = ${?HTTP_CALLER_AUTH_TOKEN}
+    # Not `Authorization` — that header carries the subject token.
+    header = "x-caller-token"
+    header = ${?HTTP_CALLER_AUTH_HEADER}
+  }
 }
 
 oauth {
   jwt {
     algorithm = "HS256"
     algorithm = ${?OAUTH_JWT_ALGORITHM}
+    # The HS256 shared secret. It must carry at least 32 bytes (256 bits) of
+    # key material or the process refuses to boot: HS256 is symmetric, so the
+    # value that verifies a token is the value that signs one, and guessing it
+    # buys the ability to MINT tokens for any subject. Generate it with
+    # `openssl rand -hex 32` (or -base64 32) and never write it in this file.
+    #
+    # The floor is measured on DECODED material at the smallest plausible
+    # reading: `openssl rand -hex 16` is 32 characters but only 16 bytes and is
+    # refused, and 32 random alphanumerics read as a 24-byte base64 body. The
+    # same floor applies to every previousSecrets entry below.
     secret = ${?OAUTH_JWT_SECRET}
+    # HS256 only. Names the secret above, matching the `kid` auth.provider
+    # stamps into every token it mints (its own default is "v0"). Leave it unset
+    # and the token header is never consulted — one secret verifies everything,
+    # which is the shape a deployment that has never rotated wants. Set it and a
+    # token carrying a different kid is refused, which is what makes the
+    # rotation block below unambiguous. Harmless under RS256/ES256/EdDSA, which
+    # match kid against the JWKS they fetch and ignore this key.
+    kid = ${?OAUTH_JWT_KID}
+    # HS256 only, and unlike `kid` this one is REFUSED at boot under
+    # RS256/ES256/EdDSA — an empty list included. Those rotate through the JWKS
+    # at jwksUri, which already carries every key the issuer publishes, so a
+    # previousSecrets block left behind on an asymmetric config configures
+    # nothing and is rejected rather than silently dropped.
+    #
+    # Secrets a rotation has retired but not finished retiring. Without them,
+    # rotating an HS256 secret is a coordinated outage: the moment the provider
+    # signs with a new value, every token already in flight is refused until
+    # both services have restarted together.
+    #
+    # Not declared here, and deliberately: nothing is being rotated yet, and an
+    # empty anchor in this shared file is exactly what would break a deployment
+    # that switches OAUTH_JWT_ALGORITHM to an asymmetric one. Add it to your own
+    # overlay while a rotation is open, then delete it once the window closed:
+    #
+    #   oauth.jwt {
+    #     kid = "v1"                    # the secret the provider signs with now
+    #     secret = ${?OAUTH_JWT_SECRET}
+    #     previousSecrets = [{
+    #       kid = "v0"                  # the secret it signed with before
+    #       secret = ${?OAUTH_JWT_PREVIOUS_SECRET}
+    #       expiresAt = "2026-09-01T00:00:00Z"   # access-token TTL + buffer
+    #     }]
+    #   }
+    #
+    # kid + secret + expiresAt is auth.provider's own previousSecrets shape, so
+    # the same pair of values moves on both sides. A token that carries no kid
+    # at all is tried against every secret listed here, which is why the list is
+    # capped at 3 entries — its length is the work one request can cost.
+    # Entries past their expiresAt stop verifying without a restart.
+    # JWKS endpoint for RS256/ES256/EdDSA. Must be https, because every key this
+    # endpoint hands back can verify tokens the service accepts: over plaintext,
+    # anyone on the network path swaps in their own signing key and forges tokens
+    # that pass. TLS is what proves the endpoint is the one you meant.
+    # Plaintext http is accepted only for loopback hosts (localhost, 127.0.0.0/8,
+    # [::1]), where no network path exists to attack — a service reached by
+    # container or DNS name is NOT loopback. Anything else fails at boot.
     jwksUri = ${?OAUTH_JWT_JWKS_URI}
+    # Bounds on the JWKS fetch, which happens inside a verify request whenever
+    # key resolution misses the cache. Leave them alone unless the provider's
+    # latency or rotation cadence demands otherwise.
+    jwksTimeoutMs = 5000
+    jwksTimeoutMs = ${?OAUTH_JWT_JWKS_TIMEOUT_MS}
+    # Minimum spacing between fetches. A token carrying an unknown kid triggers a
+    # refetch and kid is attacker-controlled, so this is also the throttle that
+    # keeps forged headers from becoming a fetch storm at the provider.
+    jwksCooldownMs = 30000
+    jwksCooldownMs = ${?OAUTH_JWT_JWKS_COOLDOWN_MS}
+    jwksCacheMaxAgeMs = 600000
+    jwksCacheMaxAgeMs = ${?OAUTH_JWT_JWKS_CACHE_MAX_AGE_MS}
     publicKey = ${?OAUTH_JWT_PUBLIC_KEY}
     publicKeyPath = ${?OAUTH_JWT_PUBLIC_KEY_PATH}
-    validate = true
-    validate = ${?OAUTH_JWT_VALIDATE}
+
+    # RFC 9068 §4 — required whenever mode = "verify". No default: booting
+    # without them fails rather than accepting any validly-signed token.
+    # A single issuer, or a list in a config file when several are acceptable.
+    issuer = ${?OAUTH_JWT_ISSUER}
+    audience = ${?OAUTH_JWT_AUDIENCE}
+    # Accepted `typ` header. at+jwt is the RFC 9068 access-token type; pinning it
+    # rejects id_tokens, refresh tokens and logout tokens signed with the same key.
+    tokenType = "at+jwt"
+    tokenType = ${?OAUTH_JWT_TOKEN_TYPE}
+
+    # Bounds on a presented token's own lifetime. Both apply in EVERY mode,
+    # insecure-decode included. `exp` itself is required and has no setting:
+    # a token that never states when it stops being valid never stops.
+    #
+    # maxTokenAgeSeconds is the ceiling on how long after issuance (`iat`) a
+    # token may still be presented, whatever `exp` its issuer chose — the
+    # backstop against a decade-long access token. Setting it makes `iat`
+    # required, which RFC 9068 §2.2 requires of an access token anyway. A day
+    # is deliberately loose; lower it to match how long your tokens really
+    # live, and raise it only for an issuer that mints genuinely long ones.
+    maxTokenAgeSeconds = 86400
+    maxTokenAgeSeconds = ${?OAUTH_JWT_MAX_TOKEN_AGE_SECONDS}
+    # Skew allowance on every time-claim comparison (exp, nbf, and the age
+    # ceiling). 0 means the verifier trusts its clock and the issuer's to agree,
+    # which is right for a sidecar sharing a host. Where they are separate
+    # machines, 60 matches the skew the paired provider allows. Capped at 300:
+    # tolerance lengthens the accepted life of every token, so an unbounded
+    # value is a way to spell "expiry optional" without writing it down.
+    clockToleranceSeconds = 0
+    clockToleranceSeconds = ${?OAUTH_JWT_CLOCK_TOLERANCE_SECONDS}
+
+    # How bearer tokens are treated. "verify" (the default) fully verifies
+    # signature, iss, aud and the typ header. "insecure-decode" is TEST-ONLY:
+    # it accepts tokens without signature verification (exp/nbf are still
+    # enforced). The value itself is the consent — a mistyped env var can flip
+    # a boolean, but it cannot produce the literal string "insecure-decode".
+    # Never set insecure-decode in production.
+    mode = "verify"
+    mode = ${?OAUTH_JWT_MODE}
   }
 }
 
+logging {
+  # Minimum level the process emits: trace/debug/info/warn/error/fatal, or
+  # silent to drop everything. Failure events the operator alerts on
+  # (jwt_verification_unavailable, verify_internal_error) emit at error.
+  #
+  # This is also the switch for the per-decision audit log. One `decision`
+  # event is emitted for every allow AND every deny, at info, carrying sub,
+  # resource, action, the rule that decided, the request id and the latency —
+  # so raising this to warn turns that stream off wholesale. It is deliberately
+  # not at warn: a deny is a normal outcome for a decision point, and routing
+  # it there would let any caller manufacture warn-level noise. The bearer
+  # token, the claims beyond sub, and the caller's `context` object are never
+  # on the line. See the README's Observability section.
+  level = "info"
+  level = ${?LOG_LEVEL}
+}
+
 attribute {
+  # What a request is described by. Every rule below decides from these
+  # attributes and nothing else, so a rule whose attribute nothing here produces
+  # can never pass — see the note in the rule block.
   collectors = [
+    # The token's `scope` claim, split into the list the scope rule reads.
     { collector = "PayloadScopeCollector" }
+    # The token's `sub`, which becomes the `subject` on the decision response
+    # and the `sub` field on the audit log line.
     { collector = "PayloadSubjectIdCollector" }
   ]
+  # Deliberately absent: anything supplying permissions or roles. This
+  # deployment authorizes from the token's scopes alone. Adding a permission
+  # rule means adding its supplier here in the same edit (#113).
 }
 
 rule {
+  # Decision for a request that collects no rule at all. "deny" (the default)
+  # keeps the verifier fail-closed; "allow" is an explicit opt-out and makes
+  # any request that matches no rule succeed.
+  onEmptyRuleSet = "deny"
+  onEmptyRuleSet = ${?RULE_ON_EMPTY_RULE_SET}
+
+  # The shipped policy is the token's own `scope` claim and nothing else: the
+  # request is allowed exactly when the token carries "<action>:<resourceType>".
+  # It works against any issuer that mints scopes without an authorization store
+  # to stand up first, and it stays fail-closed — a token carrying no scope, or
+  # the wrong one, is denied, as is a request that collects no rule at all.
+  #
+  # Rules are grouped by kind and every GROUP must pass, so one group nothing can
+  # satisfy denies every request the deployment ever sees. That is what enabling
+  # a rule collector without the attribute collector feeding it does, and it is
+  # why the permission rule below is off rather than merely unconfigured (#113).
   collectors = [
+    # Scope matching is exact and case-sensitive (RFC 6749 §3.3): the token must
+    # carry "<action>:<resourceType>" verbatim. If your issuer emits bare resource
+    # names ("document") instead ("read:document"), opt into the rewrite
+    # explicitly — it is off by default because it invents an action the issuer
+    # never wrote:
+    #   { collector = "ResourceActionScopeRuleCollector", allowBareScopeRewrite = true }
     { collector = "ResourceActionScopeRuleCollector" }
-    { collector = "ResourceActionPermissionRuleCollector" }
+
+    # NOT enabled, and not an oversight. ResourceActionPermissionRuleCollector
+    # emits a rule requiring the permission "<resource.raw>.perm:<action>" —
+    # "project:1.perm:read" for resource "project:1", action "read" — and that
+    # rule reads the permissions/roles attributes, which nothing in the
+    # `attribute.collectors` above produces. Enabled on its own it is a group no
+    # token can satisfy, i.e. a verifier that answers deny to everything.
+    #
+    # So enable it together with a supplier, in one edit — two list entries that
+    # are one decision. Add this entry to `attribute.collectors` above:
+    #
+    #   { collector = "StaticPermissionCollector", permissions = ["project:1.perm:read"] }
+    #
+    # and this entry to the list you are reading now:
+    #
+    #   { collector = "ResourceActionPermissionRuleCollector" }
+    #
+    # StaticPermissionCollector grants one fixed list to every subject, so it
+    # suits a per-deployment capability, never a per-user one. Where permissions
+    # differ by subject they live in your own store: write an AttributeCollector
+    # that reads it and register it in a module (README.md, "Adding Custom
+    # Modules", and docs/extending.md).
   ]
 }
+
+resource {
+  # How the request's `resource` string is turned into the resourceType that the
+  # scope rules above authorize. DotNotationResourceParser reads
+  # `type[:id]` segments separated by ".", and joins the segment types with "."
+  # — "project:1.member:2" is type "project.member", id "2". The separator is
+  # kept rather than rewritten to "_", so the nested type "a.b" and a flat type
+  # literally named "a_b" are two different namespaces.
+  #
+  # Strings outside that grammar are answered 400 invalid_request, never
+  # repaired: an empty segment ("a..b"), a second ":" in one segment ("a:1:2",
+  # which is refused rather than read as "a:1"), whitespace ("  a:1  " is not
+  # trimmed), and any character an OAuth scope value cannot carry. If your
+  # callers send resource strings in some other syntax, register your own
+  # ResourceParser rather than relying on this one to interpret them.
+  parser = "DotNotationResourceParser"
+}
+
+verify {
+  # Cap on `POST /verify/batch` entries. The batch endpoint exists so filtering
+  # a list of N resources costs one round trip instead of N; the cap keeps one
+  # request from turning into an unbounded amount of pipeline work.
+  maxBatchSize = 50
+  maxBatchSize = ${?VERIFY_MAX_BATCH_SIZE}
+
+  # Ceiling on the JSON body, in bytes — the limit handed to `express.json()`.
+  # Below Express's unstated 100 KB default, and the outer envelope: it is what
+  # binds first on a large batch, since the per-field limits below bound ONE
+  # entry rather than N of them. A body over it is answered
+  # `413 payload_too_large` in the same deny envelope as everything else.
+  maxBodyBytes = 65536
+  maxBodyBytes = ${?VERIFY_MAX_BODY_BYTES}
+
+  # Ceilings on the two identifiers, in characters. Whitespace in either is
+  # refused rather than trimmed — they are concatenated into the
+  # `{action}:{resourceType}` scope an issuer has to have granted, and RFC 6749
+  # §3.3 makes space the delimiter between scope values.
+  maxResourceLength = 512
+  maxResourceLength = ${?VERIFY_MAX_RESOURCE_LENGTH}
+  maxActionLength = 64
+  maxActionLength = ${?VERIFY_MAX_ACTION_LENGTH}
+
+  # Bounds on the request `context`, which is free-form caller-supplied data.
+  # `maxContextEntries` counts every property and every array element in the
+  # whole tree, at every depth — nesting is bounded rather than forbidden, since
+  # RequestContextAttributeCollector reads dot paths such as "tenant.id" — and
+  # because each level of nesting costs at least one entry, it bounds the depth
+  # too. `maxContextValueLength` bounds every string in that tree, property
+  # names included.
+  maxContextEntries = 64
+  maxContextEntries = ${?VERIFY_MAX_CONTEXT_ENTRIES}
+  maxContextValueLength = 1024
+  maxContextValueLength = ${?VERIFY_MAX_CONTEXT_VALUE_LENGTH}
+
+  # Bounds on the collector fan-out both pipelines run for every decision.
+  # Collectors are the layer that calls databases and HTTP APIs, so they are the
+  # layer that can stall; without these, one collector holding a dead socket
+  # holds the whole decision.
+  #
+  # EXCEEDING ANY OF THEM DENIES the decision — `403 collector_timeout`, with an
+  # empty `reason.groups`. It is never answered with whatever was collected in
+  # time: fewer rules is a weaker policy, and no rules at all is an ALLOW
+  # wherever `rule.onEmptyRuleSet = "allow"` is set.
+  #
+  # `collectorTimeoutMs` is one collector's own budget, counted from when that
+  # collector starts rather than from when the fan-out did, so waiting behind
+  # the concurrency cap does not spend it.
+  collectorTimeoutMs = 2000
+  collectorTimeoutMs = ${?VERIFY_COLLECTOR_TIMEOUT_MS}
+
+  # `collectorDeadlineMs` is the whole fan-out, per pipeline. The per-collector
+  # budget cannot bound a SET: once collectors queue, enough of them each
+  # finishing just inside their own budget still adds up to a request nobody is
+  # waiting for any more.
+  collectorDeadlineMs = 5000
+  collectorDeadlineMs = ${?VERIFY_COLLECTOR_DEADLINE_MS}
+
+  # `collectorConcurrency` is how many run at once, per pipeline, per decision.
+  # Higher than any realistic collector set, so an ordinary configuration still
+  # fans out in one wave; what it removes is the tail, where a wide config or a
+  # full batch multiplies into simultaneous calls against a dependency that has
+  # just started to slow down.
+  collectorConcurrency = 8
+  collectorConcurrency = ${?VERIFY_COLLECTOR_CONCURRENCY}
+
+  # Whether collectors receive the raw credential as `context.credential`
+  # (#175). "never" (the default): collectors get verified claims only — the
+  # credential is replayable, and a collector that logs its context would leak
+  # a live token. Set "expose" ONLY when a project-side collector calls a
+  # downstream API as the subject (token forwarding / exchange); this line is
+  # then the greppable record of that decision. Never log the field.
+  credentialToCollectors = "never"
+  credentialToCollectors = ${?VERIFY_CREDENTIAL_TO_COLLECTORS}
+}

package/templates/standalone/config/development.conf

@@ -0,0 +1,8 @@
+# Environment overlay for development.
+# Loaded when CONFIG_ENV (or NODE_ENV) is "development" — the default.
+# Values here override application.conf.
+#
+# Most values are controlled via environment variables (see ${?VAR}
+# substitutions in application.conf). Override entries here only when
+# you need a fixed development-specific value that cannot come from
+# an environment variable.

package/templates/standalone/config/production.conf

@@ -0,0 +1,9 @@
+# Environment overlay for production.
+# Loaded when CONFIG_ENV (or NODE_ENV) is "production".
+# Values here override application.conf.
+#
+# Most production-sensitive values should be supplied via environment
+# variables — see the ${?VAR} substitutions in application.conf.
+#
+# Override entries here only when a value must be fixed per-environment
+# rather than per-deployment.

package/templates/standalone/docker-compose.yml

@@ -8,6 +8,13 @@ services:
     volumes:
       - ./src:/home/node/src
       - ./config:/home/node/config
+    environment:
+      # application.conf binds loopback by default, which inside a container
+      # means "reachable from nothing" — the published port would never connect.
+      # Binding all interfaces is therefore an explicit opt-in per deployment,
+      # and it is why HTTP_CALLER_AUTH_TOKEN is worth setting in .env: past the
+      # container boundary, anyone who can reach the port can ask for decisions.
+      - HTTP_HOSTNAME=0.0.0.0
     env_file:
       - path: .env
         required: false

package/templates/standalone/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@o3co/auth-policy-verifier-standalone",
-	"version": "0.0.0",
+	"version": "0.4.0",
 	"private": true,
 	"license": "Apache-2.0",
 	"packageManager": "pnpm@10.29.3",
@@ -10,6 +10,7 @@
 	},
 	"scripts": {
 		"build": "tsc",
+		"typecheck": "tsc --noEmit -p tsconfig.typecheck.json",
 		"start": "node dist/main.mjs",
 		"test": "vitest run",
 		"debug": "NODE_OPTIONS='--conditions=development' tsx watch src/main.mts"
@@ -18,17 +19,18 @@
 		"@o3co/auth.policy-verifier.core": "workspace:*",
 		"@o3co/auth.policy-verifier.builtins": "workspace:*",
 		"@o3co/auth.policy-verifier.server": "workspace:*",
-		"@o3co/auth.utils": "^0.0.2",
-		"@o3co/ts.hocon": "^1.1.0",
-		"express": "^5.2.1"
+		"@o3co/auth.utils": "^0.0.4",
+		"@o3co/ts.hocon": "^1.12.0",
+		"express": "^5.2.1",
+		"pino": "^10.3.1"
 	},
 	"devDependencies": {
-		"@types/node": "^25.1.0",
-		"@types/supertest": "^7.2.0",
-		"jose": "^6.2.2",
+		"@types/node": "^26.2.0",
+		"@types/supertest": "^7.2.1",
+		"jose": "^6.2.8",
 		"supertest": "^7.2.2",
-		"tsx": "^4.21.0",
+		"tsx": "^4.23.11",
 		"typescript": "^5.9.3",
-		"vitest": "^4.1.2"
+		"vitest": "^4.1.10"
 	}
 }

package/templates/standalone/src/__tests__/configPath.test.mts

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, it } from "vitest";
+import { resolveConfigPaths } from "../configPath.js";
+
+describe("resolveConfigPaths", () => {
+	it("accepts a configDirPath with a trailing slash", () => {
+		const { applicationConfPath, envConfPath } = resolveConfigPaths(
+			"/home/node/templates/standalone/config/",
+			"production",
+		);
+		expect(applicationConfPath).toBe("/home/node/templates/standalone/config/application.conf");
+		expect(envConfPath).toBe("/home/node/templates/standalone/config/production.conf");
+	});
+
+	it("accepts a configDirPath without a trailing slash", () => {
+		const { applicationConfPath, envConfPath } = resolveConfigPaths(
+			"/home/node/templates/standalone/config",
+			"development",
+		);
+		expect(applicationConfPath).toBe("/home/node/templates/standalone/config/application.conf");
+		expect(envConfPath).toBe("/home/node/templates/standalone/config/development.conf");
+	});
+
+	it("rejects env names that resolve outside configDirPath", () => {
+		expect(() =>
+			resolveConfigPaths("/home/node/templates/standalone/config/", "../secrets"),
+		).toThrow(/resolves outside/);
+	});
+
+	it("rejects env names containing a path separator", () => {
+		expect(() =>
+			resolveConfigPaths("/home/node/templates/standalone/config/", "nested/env"),
+		).toThrow(/resolves outside/);
+	});
+});