The auth module gives JavaScript route code narrow access to host-owned authentication services. It is designed for generated and embedded hosts that already configured hostauth stores and planned Express routes. JavaScript can query audit records and operate on capability tokens, but it does not receive raw database handles or permission to bypass the route authorization pipeline.

Use this module when a route has already declared its security policy with the Express planned-auth DSL and then needs to perform a small auth-related application action. Common examples are an admin dashboard that reads recent audit records, an invite route that issues a single-use token, and a public accept route that consumes that token.

Runtime shape

A host exposes this module with require("auth") when the generated runtime plan selects the hostauth provider module:

const auth = require("auth")

The module currently exposes two namespaces:

The module depends on host-owned services. If the host has no audit query store or capability store, module setup fails when the runtime starts. That failure is intentional because JavaScript code should not silently fall back to in-memory or fake security data.

Relationship to planned routes

The auth module is not an authorization bypass. A protected route should still declare who may call it, what resource it touches, and which action is required:

app.get("/orgs/:orgId/audit")
  .auth(express.user().required())
  .resource(
    express.resource("org")
      .idFromParam("orgId")
      .mustExist()
  )
  .allow("audit.read")
  .audit("audit.records.read")
  .handle((ctx, res) => {
    const org = ctx.resource("org")
    const records = auth.audit.query()
      .tenantId(org.id)
      .limit(50)
      .run()
    res.json({ records, count: records.length })
  })

The route plan authenticates the actor and authorizes audit.read. The auth.audit.query() call only performs the data lookup after that policy has passed.

Query audit records

auth.audit.query() returns a fluent builder. Each setter records one filter, and .run() executes the query on the host-owned audit store.

const records = auth.audit.query()
  .tenantId("o1")
  .outcome("denied")
  .resource("project", "p1")
  .limit(25)
  .offset(0)
  .run()

Available setters:

Returned records use JavaScript-friendly lower-camel-case fields such as event, outcome, actorId, tenantId, resourceType, resourceId, createdAt, and optional attributes.

Issue capability tokens

A capability token represents a constrained future action. The token is returned once from .run() and should be treated like a secret. The stored record keeps only a hash.

const issued = auth.capabilities.issue("org-invite")
  .resource("org", org.id)
  .tenantId(org.id)
  .claimString("email", body.email || "")
  .claimString("role", body.role || "viewer")
  .ttlSeconds(900)
  .singleUse(true)
  .createdBy(ctx.actor.id)
  .run()

res.json({
  token: issued.token,
  capabilityId: issued.capability.id,
  expiresAt: issued.capability.expiresAt
})

Available issue setters:

Use capability claims for application payload that is needed later, such as invite email and role. Keep claims small and non-secret unless the storage and audit path for that data is acceptable.

Validate versus consume

Validation checks a token without marking it used. Consumption validates and then marks a single-use token used. This distinction matters when you need to check expected type or resource before burning a token.

const preview = auth.capabilities.validate(token)
  .expectedType("org-invite")
  .expectedResource("org", "o1")
  .run()

const accepted = auth.capabilities.consume(token)
  .expectedType("org-invite")
  .expectedResource("org", "o1")
  .run()

Available validate/consume setters:

A consumed single-use token has usedAt in the returned record. Reusing the same token throws an error equivalent to capability.ErrUsed.

Revoke capabilities

Revocation invalidates a capability by id. The current JavaScript builder accepts a reason for readability, but the underlying service stores only the revoked timestamp.

auth.capabilities.revoke()
  .id(capabilityId)
  .reason("user_request")
  .run()

A successful revoke returns { revoked: true, id }.

Map errors deliberately

Capability errors are normal application outcomes. A public accept route should not expose every failure as a server error:

app.post("/org-invites/accept")
  .public()
  .audit("org.invite.accepted")
  .handle((ctx, res) => {
    const body = ctx.body || {}
    try {
      const accepted = auth.capabilities.consume(body.token || "")
        .expectedType("org-invite")
        .expectedResource("org", "o1")
        .run()
      res.json({ orgId: accepted.resourceId, email: accepted.claims.email })
    } catch (err) {
      const message = String((err && err.message) || err || "capability rejected")
      const status = message.includes("already used") ? 409 : 400
      res.status(status).json({ error: message })
    }
  })

A typical mapping is:

Example 21 route ownership

examples/xgoja/21-generated-host-auth is the canonical full generated-host example. Native Go handlers own only OIDC/session lifecycle routes. The JavaScript file owns application-specific routes such as audit dashboards and org invites.

Run the fast generated-host smoke:

make -C examples/xgoja/21-generated-host-auth smoke

Run the real local Keycloak/Postgres smoke:

make -C examples/xgoja/21-generated-host-auth compose-smoke

The compose smoke logs in through the example Keycloak realm, seeds demo appauth resources and membership rows, exercises the JavaScript-owned audit/invite routes, and verifies that a reused invite token returns 409.

Troubleshooting

See also

• goja-repl help express-auth-user-guide
• goja-repl help express-auth-examples
• xgoja help generated-auth-javascript-apis
• xgoja help hostauth-config-reference
• xgoja help auth-stores-reference