@stratum-hq/hono 1.1.0 → 1.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +32 -4
- package/dist/middleware.d.ts +20 -1
- package/dist/middleware.d.ts.map +1 -1
- package/dist/middleware.js +8 -0
- package/dist/middleware.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -10,15 +10,28 @@ npm install @stratum-hq/hono @stratum-hq/sdk @stratum-hq/core hono
|
|
|
10
10
|
|
|
11
11
|
## Quick Start
|
|
12
12
|
|
|
13
|
+
Read the tenant from a claim of a verified JWT:
|
|
14
|
+
|
|
13
15
|
```typescript
|
|
14
16
|
import { Hono } from "hono";
|
|
17
|
+
import { jwt } from "hono/jwt";
|
|
15
18
|
import { stratumMiddleware } from "@stratum-hq/hono";
|
|
16
19
|
import { getTenantContext } from "@stratum-hq/sdk";
|
|
17
20
|
|
|
18
21
|
const app = new Hono();
|
|
19
22
|
|
|
23
|
+
const jwtSecret = process.env.JWT_SECRET;
|
|
24
|
+
if (!jwtSecret) {
|
|
25
|
+
throw new Error("JWT_SECRET is required to verify bearer tokens.");
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
// hono/jwt rejects a missing or invalid bearer token with 401 and stores the
|
|
29
|
+
// verified claims as jwtPayload. Register it before stratumMiddleware.
|
|
30
|
+
app.use("*", jwt({ secret: jwtSecret, alg: "HS256" }));
|
|
31
|
+
|
|
20
32
|
app.use("*", stratumMiddleware({
|
|
21
|
-
|
|
33
|
+
// Read the tenant from the verified `tenant_id` claim
|
|
34
|
+
jwtClaim: "tenant_id",
|
|
22
35
|
// Optional: fetch the full tenant context (ancestry, config, permissions)
|
|
23
36
|
resolve: async (tenantId) => sdkClient.resolveTenant(tenantId),
|
|
24
37
|
}));
|
|
@@ -30,6 +43,19 @@ app.get("/users", (c) => {
|
|
|
30
43
|
});
|
|
31
44
|
```
|
|
32
45
|
|
|
46
|
+
`stratumMiddleware` does not verify a token itself; `jwtClaim` reads the `jwtPayload` that Hono's JWT middleware sets.
|
|
47
|
+
|
|
48
|
+
### Client-controlled sources
|
|
49
|
+
|
|
50
|
+
`pathParam` and `header` both take the tenant ID from the request as the client sent it, so any client can name another tenant. Use them only when something you control authorizes the caller for that tenant (for example a later middleware that compares it with a claim of the verified token). Path parameter mode therefore requires `trustPathParam: true`. Header mode requires `trustTenantHeader: true`, which is appropriate only when a gateway you control sets the header, removes any client copy, and is the only way to reach the server:
|
|
51
|
+
|
|
52
|
+
```typescript
|
|
53
|
+
// Your application authorizes the caller for the tenant in the path.
|
|
54
|
+
app.use("/tenants/:tenantId/*", stratumMiddleware({ pathParam: "tenantId", trustPathParam: true }));
|
|
55
|
+
|
|
56
|
+
app.use("*", stratumMiddleware({ header: "x-tenant-id", trustTenantHeader: true }));
|
|
57
|
+
```
|
|
58
|
+
|
|
33
59
|
## Options
|
|
34
60
|
|
|
35
61
|
`stratumMiddleware(options)` extracts the tenant ID from exactly one source, in this precedence:
|
|
@@ -37,15 +63,17 @@ app.get("/users", (c) => {
|
|
|
37
63
|
| Option | Behavior |
|
|
38
64
|
|--------|----------|
|
|
39
65
|
| `jwtClaim` | Read the claim from Hono's `jwtPayload` context variable |
|
|
40
|
-
| `pathParam` | Read a URL path parameter (`c.req.param(name)`) |
|
|
41
|
-
| `header` | Read a request header (default: `x-tenant-id`) |
|
|
66
|
+
| `pathParam` | Read a URL path parameter (`c.req.param(name)`). Requires `trustPathParam: true`. Client-controlled: authorize the caller for that tenant separately |
|
|
67
|
+
| `header` | Read a request header (default: `x-tenant-id`). Requires `trustTenantHeader: true` |
|
|
68
|
+
| `trustPathParam` | Allow path parameter mode. Without it, `stratumMiddleware` throws at construction when `pathParam` is set and `jwtClaim` is not (default: `false`) |
|
|
69
|
+
| `trustTenantHeader` | Allow header mode. Without it, and without `jwtClaim` or `pathParam`, `stratumMiddleware` throws at construction (default: `false`) |
|
|
42
70
|
| `resolve` | Optional callback `(tenantId) => TenantContext` to populate ancestry, config, and permissions |
|
|
43
71
|
|
|
44
72
|
If no tenant ID is found, the middleware responds with `400 { error: "Missing tenant ID" }`. If `resolve` rejects with a tenant error from `@stratum-hq/core`, for example from `StratumClient.resolveTenant`, the middleware responds with 404 `TENANT_NOT_FOUND`, 403 `TENANT_SUSPENDED`, 410 `TENANT_ARCHIVED`, or 403 `FORBIDDEN`. A control plane timeout gets 504 `CONTROL_PLANE_TIMEOUT`. An `UnauthorizedError` for the SDK's own API key gets 500 `CONTROL_PLANE_AUTH_FAILED` and a `console.error` line. Other errors go to the Hono error handler. Without a `resolve` callback the context is a placeholder (empty config/permissions) — provide `resolve` for real tenant data.
|
|
45
73
|
|
|
46
74
|
## Features
|
|
47
75
|
|
|
48
|
-
- Tenant extraction from
|
|
76
|
+
- Tenant extraction from a verified JWT claim, a path parameter, or a trusted-gateway header
|
|
49
77
|
- Binds tenant context via `runWithTenantContext` so downstream handlers can call `getTenantContext()`
|
|
50
78
|
- Lightweight — structural types only, no heavy dependencies
|
|
51
79
|
|
package/dist/middleware.d.ts
CHANGED
|
@@ -5,8 +5,27 @@ export interface StratumMiddlewareOptions {
|
|
|
5
5
|
header?: string;
|
|
6
6
|
/** JWT claim name to extract tenant ID from */
|
|
7
7
|
jwtClaim?: string;
|
|
8
|
-
/**
|
|
8
|
+
/**
|
|
9
|
+
* URL path parameter name to extract tenant ID from. The client chooses the
|
|
10
|
+
* path, so this also requires `trustPathParam: true`.
|
|
11
|
+
*/
|
|
9
12
|
pathParam?: string;
|
|
13
|
+
/**
|
|
14
|
+
* Allow reading the tenant ID from the `pathParam` URL path parameter. A
|
|
15
|
+
* client can put any tenant ID in the path, so this must be enabled
|
|
16
|
+
* explicitly, and only when your application separately authorizes the
|
|
17
|
+
* caller for that tenant. Without it, `stratumMiddleware` throws at
|
|
18
|
+
* construction when `pathParam` is the tenant source. Default: false.
|
|
19
|
+
*/
|
|
20
|
+
trustPathParam?: boolean;
|
|
21
|
+
/**
|
|
22
|
+
* Allow reading the tenant ID from a request header. A client can set any
|
|
23
|
+
* header, so this must be enabled explicitly, and only when a gateway you
|
|
24
|
+
* control sets the header and strips any client-sent copy. Without it,
|
|
25
|
+
* `stratumMiddleware` throws at construction unless `jwtClaim` or
|
|
26
|
+
* `pathParam` is set. Default: false.
|
|
27
|
+
*/
|
|
28
|
+
trustTenantHeader?: boolean;
|
|
10
29
|
/**
|
|
11
30
|
* Optional callback to resolve a full tenant context from the tenant ID.
|
|
12
31
|
* When provided, the middleware will call this to obtain ancestry, config,
|
package/dist/middleware.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAG7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAG9D,MAAM,WAAW,wBAAwB;IACvC,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB
|
|
1
|
+
{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAG7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAG9D,MAAM,WAAW,wBAAwB;IACvC,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,GAAG,qBAAqB,CAAC;CACxF;AAkBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,wBAA6B,GACrC,iBAAiB,CA0DnB"}
|
package/dist/middleware.js
CHANGED
|
@@ -20,6 +20,14 @@ function extractFromPathParam(c, param) {
|
|
|
20
20
|
* AsyncLocalStorage context via `runWithTenantContext()`.
|
|
21
21
|
*/
|
|
22
22
|
export function stratumMiddleware(options = {}) {
|
|
23
|
+
if (!options.jwtClaim && options.pathParam && options.trustPathParam !== true) {
|
|
24
|
+
throw new Error("[stratum] stratumMiddleware would read the tenant ID from an unverified URL path parameter. " +
|
|
25
|
+
"Use jwtClaim with a verified JWT, or set trustPathParam: true if your application authorizes the caller for that tenant.");
|
|
26
|
+
}
|
|
27
|
+
if (!options.jwtClaim && !options.pathParam && options.trustTenantHeader !== true) {
|
|
28
|
+
throw new Error("[stratum] stratumMiddleware would read the tenant ID from an unverified request header. " +
|
|
29
|
+
"Use jwtClaim with a verified JWT, or set trustTenantHeader: true if a trusted gateway sets the header.");
|
|
30
|
+
}
|
|
23
31
|
return async (c, next) => {
|
|
24
32
|
let tenantId;
|
|
25
33
|
if (options.jwtClaim) {
|
package/dist/middleware.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEvG,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;
|
|
1
|
+
{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"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"}
|