@@ -19,12 +19,12 @@ This split allows commands to work without auth when no credential is found, and
1919
2020All credentials use a discriminated union on the ` type ` field:
2121
22- | Type | Interface | HTTP Header |
23- | --------- | ------------------- | --------------------------------------- |
24- | ` bearer ` | ` BearerCredential ` | ` Authorization: Bearer <token> ` |
25- | ` basic ` | ` BasicCredential ` | ` Authorization: Basic base64(user:pass) ` |
26- | ` api-key ` | ` ApiKeyCredential ` | ` <headerName>: <key> ` |
27- | ` custom ` | ` CustomCredential ` | Arbitrary ` headers ` record |
22+ | Type | Interface | HTTP Header |
23+ | --------- | ------------------ | - --------------------------------------- |
24+ | ` bearer ` | ` BearerCredential ` | ` Authorization: Bearer <token> ` |
25+ | ` basic ` | ` BasicCredential ` | ` Authorization: Basic base64(user:pass) ` |
26+ | ` api-key ` | ` ApiKeyCredential ` | ` <headerName>: <key> ` |
27+ | ` custom ` | ` CustomCredential ` | Arbitrary ` headers ` record |
2828
2929``` ts
3030interface BearerCredential {
@@ -54,10 +54,10 @@ interface CustomCredential {
5454
5555Credentials are persisted as JSON files using kidd's file store system.
5656
57- | Location | Path | Resolution order |
58- | -------- | ------------------------------- | ---------------- |
59- | Local | ` ./<cli-name>/auth.json ` | Checked first |
60- | Global | ` ~/<cli-name>/auth.json ` | Checked second |
57+ | Location | Path | Resolution order |
58+ | -------- | ------------------------ | ---------------- |
59+ | Local | ` ./<cli-name>/auth.json ` | Checked first |
60+ | Global | ` ~/<cli-name>/auth.json ` | Checked second |
6161
6262The file contains the raw credential object:
6363
@@ -80,9 +80,9 @@ Reads a bearer token from `process.env`.
8080{ source : ' env' , tokenVar : ' GITHUB_TOKEN' }
8181```
8282
83- | Option | Type | Default | Description |
84- | ---------- | -------- | --------------------- | ------ ------------------------- |
85- | ` tokenVar ` | ` string ` | ` <CLI_NAME>_TOKEN ` | Environment variable name |
83+ | Option | Type | Default | Description |
84+ | ---------- | -------- | ------------------ | ------------------------- |
85+ | ` tokenVar ` | ` string ` | ` <CLI_NAME>_TOKEN ` | Environment variable name |
8686
8787The default variable name is derived from the CLI name: ` my-app ` becomes ` MY_APP_TOKEN ` .
8888
@@ -94,10 +94,10 @@ Reads a bearer token from a `.env` file without mutating `process.env`.
9494{ source : ' dotenv' , tokenVar : ' API_TOKEN' , path : ' ./.env.local' }
9595```
9696
97- | Option | Type | Default | Description |
98- | ---------- | -------- | ------------------ | ------------------------------- |
99- | ` tokenVar ` | ` string ` | ` <CLI_NAME>_TOKEN ` | Variable name within the file |
100- | ` path ` | ` string ` | ` $CWD/.env ` | Path to the dotenv file |
97+ | Option | Type | Default | Description |
98+ | ---------- | -------- | ------------------ | ----------------------------- |
99+ | ` tokenVar ` | ` string ` | ` <CLI_NAME>_TOKEN ` | Variable name within the file |
100+ | ` path ` | ` string ` | ` $CWD/.env ` | Path to the dotenv file |
101101
102102### ` file ` -- JSON File
103103
@@ -107,10 +107,10 @@ Reads any credential type from a JSON file on disk via kidd's store system.
107107{ source : ' file' , filename : ' auth.json' , dirName : ' .my-app' }
108108```
109109
110- | Option | Type | Default | Description |
111- | ---------- | -------- | ----------------- | ---- ----------------------------- |
112- | ` filename ` | ` string ` | ` 'auth.json' ` | Filename within the store dir |
113- | ` dirName ` | ` string ` | ` .<cli-name> ` | Store directory name |
110+ | Option | Type | Default | Description |
111+ | ---------- | -------- | ------------- | ----------------------------- |
112+ | ` filename ` | ` string ` | ` 'auth.json' ` | Filename within the store dir |
113+ | ` dirName ` | ` string ` | ` .<cli-name> ` | Store directory name |
114114
115115### ` oauth ` -- OAuth Browser Flow
116116
@@ -120,12 +120,12 @@ Opens the user's browser to an auth URL, starts a local HTTP server to receive t
120120{ source : ' oauth' , authUrl : ' https://example.com/auth' , port : 0 , timeout : 120_000 }
121121```
122122
123- | Option | Type | Default | Description |
124- | -------------- | -------- | -------------- | ---------------- ---------------------------- |
125- | ` authUrl ` | ` string ` | -- | Authorization URL (required) |
126- | ` port ` | ` number ` | ` 0 ` (random) | Local server port |
127- | ` callbackPath ` | ` string ` | ` '/callback' ` | Callback endpoint path |
128- | ` timeout ` | ` number ` | ` 120_000 ` | Timeout in milliseconds |
123+ | Option | Type | Default | Description |
124+ | -------------- | -------- | ------------- | ---------------------------- |
125+ | ` authUrl ` | ` string ` | -- | Authorization URL (required) |
126+ | ` port ` | ` number ` | ` 0 ` (random) | Local server port |
127+ | ` callbackPath ` | ` string ` | ` '/callback' ` | Callback endpoint path |
128+ | ` timeout ` | ` number ` | ` 120_000 ` | Timeout in milliseconds |
129129
130130The auth URL receives a ` callback_url ` query parameter pointing to the local server. The OAuth provider must POST a JSON body ` { "token": "<value>" } ` to this URL on success.
131131
@@ -137,9 +137,9 @@ Prompts the user for a token via a masked password input.
137137{ source : ' prompt' , message : ' Enter your API token:' }
138138```
139139
140- | Option | Type | Default | Description |
141- | --------- | -------- | ------------------------ | ------- -------------- |
142- | ` message ` | ` string ` | ` 'Enter your API key' ` | Prompt message |
140+ | Option | Type | Default | Description |
141+ | --------- | -------- | ---------------------- | -------------- |
142+ | ` message ` | ` string ` | ` 'Enter your API key' ` | Prompt message |
143143
144144### ` custom ` -- User-Provided Function
145145
@@ -155,19 +155,19 @@ Calls a user-supplied function that returns a credential or null.
155155}
156156```
157157
158- | Option | Type | Description |
159- | ---------- | -------------------------------------------------------- | -- ----------------- |
158+ | Option | Type | Description |
159+ | ---------- | ----------------------------------------------------------------- | ----------------- |
160160| ` resolver ` | ` () => Promise<AuthCredential \| null> \| AuthCredential \| null ` | Resolver function |
161161
162162## AuthContext
163163
164164The auth middleware decorates ` ctx.auth ` with an ` AuthContext ` :
165165
166- | Property | Type | Description |
167- | ----------------- | --------------------------------------------- | ---------------------------------------------- |
168- | ` credential() ` | ` AuthCredential \| null ` | Passively resolved credential (file, env) |
169- | ` authenticated() ` | ` boolean ` | Whether a passive credential exists |
170- | ` authenticate() ` | ` AsyncResult<AuthCredential, LoginError> ` | Run interactive resolvers, persist, and return |
166+ | Property | Type | Description |
167+ | ----------------- | ----------------------------------------- | ---------------------------------------------- |
168+ | ` credential() ` | ` AuthCredential \| null ` | Passively resolved credential (file, env) |
169+ | ` authenticated() ` | ` boolean ` | Whether a passive credential exists |
170+ | ` authenticate() ` | ` AsyncResult<AuthCredential, LoginError> ` | Run interactive resolvers, persist, and return |
171171
172172### ` ctx.auth.authenticate() `
173173
@@ -180,10 +180,10 @@ if (error) {
180180}
181181```
182182
183- | LoginError ` type ` | Description |
184- | ------------------- | ----- ----------------------------------------- |
185- | ` 'no_credential' ` | No resolver produced a credential |
186- | ` 'save_failed' ` | Credential resolved but failed to persist |
183+ | LoginError ` type ` | Description |
184+ | ----------------- | ----------------------------------------- |
185+ | ` 'no_credential' ` | No resolver produced a credential |
186+ | ` 'save_failed' ` | Credential resolved but failed to persist |
187187
188188## HTTP Integration
189189
0 commit comments