@farm.js/unkey 0.1.49 → 0.1.51-beta.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 +94 -3
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,11 +1,102 @@
|
|
|
1
1
|
# @farm.js/unkey
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
API keys for Farm.js applications, backed by Unkey. The integration gives server code typed calls to
|
|
4
|
+
create, verify, update, revoke, and delete keys, and can verify the key on matching requests before
|
|
5
|
+
they reach a page or API route.
|
|
4
6
|
|
|
5
7
|
See [Stability and Support](https://farmjs.dev/docs/stability) for what this package guarantees.
|
|
6
8
|
|
|
9
|
+
## Install
|
|
10
|
+
|
|
7
11
|
```bash
|
|
8
|
-
|
|
12
|
+
pnpm add @farm.js/unkey
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
The package has no SDK dependency: it calls Unkey's HTTP API with `fetch`. To scaffold the registry
|
|
16
|
+
entry, a protected API route, and a test page at `/integrations/unkey` in an existing app, run
|
|
17
|
+
`farm add integration unkey --ui`.
|
|
18
|
+
|
|
19
|
+
## Configure
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
// src/lib/integrations.ts
|
|
23
|
+
import { unkey } from "@farm.js/unkey";
|
|
24
|
+
|
|
25
|
+
export const appIntegrations = {
|
|
26
|
+
apiKeys: unkey({
|
|
27
|
+
protectedRoutes: ["/api/protected(.*)"],
|
|
28
|
+
protection: { permissions: "documents.read" },
|
|
29
|
+
}),
|
|
30
|
+
} as const;
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
| Variable | Purpose |
|
|
34
|
+
| ---------------- | -------------------------------------------------------------- |
|
|
35
|
+
| `UNKEY_ROOT_KEY` | Root key for the Unkey API. Required unless `instance` is set. |
|
|
36
|
+
| `UNKEY_API_ID` | API that new keys are created in. |
|
|
37
|
+
| `UNKEY_BASE_URL` | Unkey API origin. Defaults to `https://api.unkey.com`. |
|
|
38
|
+
|
|
39
|
+
`rootKey`, `apiId`, `baseUrl`, and `fetch` can be passed as options instead. Keep the root key in
|
|
40
|
+
server-only environment variables.
|
|
41
|
+
|
|
42
|
+
## Manage keys from server code
|
|
43
|
+
|
|
44
|
+
The `create`, `verify`, `update`, `revoke`, and `delete-key` routes mount under `/api/unkey` and are
|
|
45
|
+
server-only. They answer in-process calls through `api` from `createIntegrations`, and a plain HTTP
|
|
46
|
+
request to them gets `404`, so the root key is never reachable from the browser.
|
|
47
|
+
|
|
48
|
+
```ts
|
|
49
|
+
// a server-only module
|
|
50
|
+
import { api } from "./api";
|
|
51
|
+
|
|
52
|
+
const created = await api.apiKeys.create({
|
|
53
|
+
body: { externalId: user.id, permissions: ["documents.read"] },
|
|
54
|
+
});
|
|
55
|
+
|
|
56
|
+
const verified = await api.apiKeys.verify({
|
|
57
|
+
body: { key: created.data!.key, permissions: "documents.read" },
|
|
58
|
+
});
|
|
9
59
|
```
|
|
10
60
|
|
|
11
|
-
|
|
61
|
+
Creating a key needs an API id from `UNKEY_API_ID`, the `apiId` option, or `body.apiId`, and the
|
|
62
|
+
route answers `400` without one. `paths.basePath` moves every route, and `paths.create` and its
|
|
63
|
+
siblings move one.
|
|
64
|
+
|
|
65
|
+
## Protect routes
|
|
66
|
+
|
|
67
|
+
When a request matches `protectedRoutes` (or `protection.matcher`), the key is verified before the
|
|
68
|
+
handler runs.
|
|
69
|
+
|
|
70
|
+
- The key is read from `authorization`, with or without a `Bearer` prefix, then from `x-api-key`.
|
|
71
|
+
Set `protection.headers` to read other headers.
|
|
72
|
+
- `protection.permissions` and `protection.tags` are checked as part of verification.
|
|
73
|
+
- A missing or invalid key gets `401` with a `code`, and a rate limited key gets `429`.
|
|
74
|
+
`protection.onDenied` can return a response of its own.
|
|
75
|
+
- A verified result is stored in request context as `unkey` (or `protection.contextKey`) and
|
|
76
|
+
`apiKey`, plus `apiKeyId` and `apiKeyOwnerId` when Unkey returns them. Set
|
|
77
|
+
`protection.exposeToPage` to make them readable from pages. `protection.onVerified` can return a
|
|
78
|
+
response instead of continuing.
|
|
79
|
+
|
|
80
|
+
## Bring your own client
|
|
81
|
+
|
|
82
|
+
```ts
|
|
83
|
+
import { createUnkeyClient, unkey } from "@farm.js/unkey";
|
|
84
|
+
|
|
85
|
+
const unkeyClient = createUnkeyClient({
|
|
86
|
+
rootKey: process.env.UNKEY_ROOT_KEY,
|
|
87
|
+
apiId: process.env.UNKEY_API_ID,
|
|
88
|
+
});
|
|
89
|
+
|
|
90
|
+
export const apiKeys = unkey({ instance: unkeyClient });
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
`instance` accepts any object implementing the exported `UnkeyClient` interface, which also suits
|
|
94
|
+
test doubles. With an instance, Farm no longer requires `UNKEY_ROOT_KEY`. The older `client` option
|
|
95
|
+
is a deprecated alias for `instance`.
|
|
96
|
+
|
|
97
|
+
## Documentation
|
|
98
|
+
|
|
99
|
+
- [Unkey integration](https://farmjs.dev/docs/integrations/unkey)
|
|
100
|
+
|
|
101
|
+
Report issues and find examples in the
|
|
102
|
+
[Farm.js repository](https://github.com/farming-labs/farm.js).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@farm.js/unkey",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.51-beta.0",
|
|
4
4
|
"description": "Unkey integration for Farm.js",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -25,8 +25,8 @@
|
|
|
25
25
|
"access": "public"
|
|
26
26
|
},
|
|
27
27
|
"dependencies": {
|
|
28
|
-
"@farm.js/core": "0.1.
|
|
29
|
-
"@farm.js/integration-utils": "0.1.
|
|
28
|
+
"@farm.js/core": "0.1.51-beta.0",
|
|
29
|
+
"@farm.js/integration-utils": "0.1.51-beta.0"
|
|
30
30
|
},
|
|
31
31
|
"scripts": {
|
|
32
32
|
"build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",
|