@kana-ai/edgar-ext-github 0.1.0 → 0.1.2
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 +14 -3
- package/dist/src/api/app.d.ts +7 -2
- package/dist/src/api/app.js +4 -2
- package/dist/src/api/client.d.ts +5 -1
- package/dist/src/api/client.js +17 -5
- package/dist/src/index.js +3 -2
- package/edgar-extension.json +5 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -354,11 +354,22 @@ With `app` set, `GITHUB_TOKEN` holds the App's private key (the PEM file GitHub
|
|
|
354
354
|
GITHUB_TOKEN = { env = "GITHUB_APP_PRIVATE_KEY" }
|
|
355
355
|
```
|
|
356
356
|
|
|
357
|
-
The key is a secret of the call: the engine's redaction holds it, it is sent nowhere, and only the JWT signed with it goes to `api.github.com`. A key that is not a PEM private key is `permanent_failure(unauthenticated)` before any request. A refused mint is the call's failure, and nothing is kept.
|
|
357
|
+
The key is a secret of the call: the engine's redaction holds it, it is sent nowhere, and only the JWT signed with it goes to `api.github.com`. A key that is not a PEM private key is `permanent_failure(unauthenticated)` before any request. A refused mint is the call's failure, and nothing is kept.
|
|
358
|
+
|
|
359
|
+
EDGAR's own git, which clones, fetches and pushes each repository, gets an installation token of the App too, when the project names the extension for `github.com`:
|
|
360
|
+
|
|
361
|
+
```toml
|
|
362
|
+
[sandbox]
|
|
363
|
+
git_tokens = { "github.com" = { extension = "github" } }
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
The extension's `git_credential` then answers the engine's ask for `github.com` with the held installation token, or a new one, and its `expires_at`. The engine asks again when the token it holds expires within five minutes, and keeps the token in memory only. The App needs `contents: write` on each repository of `[services]`. With no `app`, `git_credential` answers `GITHUB_TOKEN` itself, with no expiry. An ask for another host is `permanent_failure(invalid)`. With `app` set and `git_tokens` still naming `GITHUB_TOKEN`, `edgar check` reports a `C005` error, because git cannot send the private key as a token.
|
|
367
|
+
|
|
368
|
+
`push_branch` runs git in the sandbox, and EDGAR gives that git no token, with or without an App: it pushes with the credentials that git in the sandbox has. The built-in workflows push in their `push` stage, with EDGAR's own git, so they push with the App.
|
|
358
369
|
|
|
359
370
|
## Secrets
|
|
360
371
|
|
|
361
|
-
- `GITHUB_TOKEN`: a token that can push, open and merge pull requests, or the App's private key when `app` is set. It reaches only `api.github.com`.
|
|
372
|
+
- `GITHUB_TOKEN`: a token that can push, open and merge pull requests, or the App's private key when `app` is set. It reaches only `api.github.com`. EDGAR's own git sends the token to `github.com` as `[sandbox] git_tokens` says, or with `{ extension = "github" }`, an installation token that the extension mints.
|
|
362
373
|
|
|
363
374
|
### What the token must be able to do
|
|
364
375
|
|
|
@@ -386,7 +397,7 @@ No check reads a token's rights ahead of its first call: the engine runs no exte
|
|
|
386
397
|
}
|
|
387
398
|
```
|
|
388
399
|
|
|
389
|
-
- `GITHUB_WEBHOOK_SECRET`: the engine checks the `hmac-sha256` signature of `/hooks/github/events` with it. The delivery id is `X-GitHub-Delivery`.
|
|
400
|
+
- `GITHUB_WEBHOOK_SECRET`: the engine checks the `hmac-sha256` signature of `/hooks/github/events` with it. The delivery id is `X-GitHub-Delivery`. Until EDGAR serves a webhook route, it needs no entry in `[secrets]` and no value.
|
|
390
401
|
|
|
391
402
|
## Errors
|
|
392
403
|
|
package/dist/src/api/app.d.ts
CHANGED
|
@@ -6,11 +6,16 @@ export interface App {
|
|
|
6
6
|
readonly id: number | string;
|
|
7
7
|
readonly installation: number;
|
|
8
8
|
}
|
|
9
|
+
/** A minted installation token and its expiry, in Unix milliseconds. */
|
|
10
|
+
export interface Held {
|
|
11
|
+
readonly token: string;
|
|
12
|
+
readonly expiresAt: number;
|
|
13
|
+
}
|
|
9
14
|
/** The JWT that signs the App in, RS256 with its private key, issued a minute back for clock drift and valid for nine minutes; a key that is not a PEM private key is `unauthenticated`. */
|
|
10
15
|
export declare function appJwt(app: App, pem: string, now?: number): Result<string, Failure>;
|
|
11
16
|
/** The installation token minted for `app` that is still good at `now`, past which it is minted again. */
|
|
12
|
-
export declare function heldToken(app: App, now?: number):
|
|
17
|
+
export declare function heldToken(app: App, now?: number): Held | undefined;
|
|
13
18
|
/** Keeps a minted installation token in this process's memory until five minutes before `expires_at`. */
|
|
14
|
-
export declare function holdToken(app: App, token: string, expiresAt: string):
|
|
19
|
+
export declare function holdToken(app: App, token: string, expiresAt: string): Held;
|
|
15
20
|
/** Forgets every held token, for a test that starts clean. */
|
|
16
21
|
export declare function forgetTokens(): void;
|
package/dist/src/api/app.js
CHANGED
|
@@ -20,11 +20,13 @@ const keyOf = (app) => `${String(app.id)}:${String(app.installation)}`;
|
|
|
20
20
|
/** The installation token minted for `app` that is still good at `now`, past which it is minted again. */
|
|
21
21
|
export function heldToken(app, now = Date.now()) {
|
|
22
22
|
const found = held.get(keyOf(app));
|
|
23
|
-
return found !== undefined && found.expiresAt - RENEW_BEFORE_MS > now ? found
|
|
23
|
+
return found !== undefined && found.expiresAt - RENEW_BEFORE_MS > now ? found : undefined;
|
|
24
24
|
}
|
|
25
25
|
/** Keeps a minted installation token in this process's memory until five minutes before `expires_at`. */
|
|
26
26
|
export function holdToken(app, token, expiresAt) {
|
|
27
|
-
|
|
27
|
+
const minted = { token, expiresAt: Date.parse(expiresAt) };
|
|
28
|
+
held.set(keyOf(app), minted);
|
|
29
|
+
return minted;
|
|
28
30
|
}
|
|
29
31
|
/** Forgets every held token, for a test that starts clean. */
|
|
30
32
|
export function forgetTokens() {
|
package/dist/src/api/client.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { type Ctx, type Failure, type Result } from "@kana-ai/edgar-sdk";
|
|
1
|
+
import { type Ctx, type Failure, type GitToken, type Result } from "@kana-ai/edgar-sdk";
|
|
2
2
|
import { z } from "zod";
|
|
3
3
|
/** The secret every GitHub call sends. */
|
|
4
4
|
export declare const TOKEN = "GITHUB_TOKEN";
|
|
@@ -14,6 +14,10 @@ export declare const LOG_HOSTS: readonly ["*.blob.core.windows.net", "*.actions.
|
|
|
14
14
|
/** The answer of one GitHub call: the parsed body, or the failure it maps to. */
|
|
15
15
|
export type Reply<T> = Result<T, Failure>;
|
|
16
16
|
type Method = "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
|
|
17
|
+
/** The host whose git EDGAR's own git reaches with a GitHub token. */
|
|
18
|
+
export declare const GIT_HOST = "github.com";
|
|
19
|
+
/** The token EDGAR's own git sends to `github.com`: with `[extensions.github] app`, an installation token and its expiry, minted or held as an API call's is; else `GITHUB_TOKEN` itself, which does not expire. */
|
|
20
|
+
export declare function gitToken(ctx: Ctx<typeof TOKEN>, host: string): Promise<Reply<GitToken>>;
|
|
17
21
|
/** Calls the GitHub REST API and parses the answer with `schema`. */
|
|
18
22
|
export declare function github<T>(ctx: Ctx<typeof TOKEN>, method: Method, path: string, schema: z.ZodType<T>, body?: Readonly<Record<string, unknown>>): Promise<Reply<T>>;
|
|
19
23
|
/** Calls the GitHub REST API like `github`, with the requests the token has left from `x-ratelimit-remaining`, 0 when the answer has none. */
|
package/dist/src/api/client.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { attemptAsync, err, failure, fetchFailure, limitFromHeaders, ok, reportLimit, unwrapOr, } from "@kana-ai/edgar-sdk";
|
|
1
|
+
import { attemptAsync, err, failure, fetchFailure, limitFromHeaders, ok, permanentFailure, reportLimit, unwrapOr, } from "@kana-ai/edgar-sdk";
|
|
2
2
|
import { z } from "zod";
|
|
3
3
|
import { appJwt, heldToken, holdToken } from "#api/app";
|
|
4
4
|
import { limits, mapFailure } from "#api/failures";
|
|
@@ -36,7 +36,7 @@ async function send(ctx, method, path, authorization, body) {
|
|
|
36
36
|
const json = unwrapOr(await attemptAsync(async () => await response.json(), () => null), null);
|
|
37
37
|
return err(mapFailure(response.status, response.headers, json, context));
|
|
38
38
|
}
|
|
39
|
-
const minted = z.object({ token: z.string(), expires_at: z.
|
|
39
|
+
const minted = z.object({ token: z.string().min(1), expires_at: z.iso.datetime() });
|
|
40
40
|
/** An installation token of `app`: the one held, or one minted with the App's JWT and then held. */
|
|
41
41
|
async function installationToken(ctx, app) {
|
|
42
42
|
const known = heldToken(app);
|
|
@@ -53,8 +53,7 @@ async function installationToken(ctx, app) {
|
|
|
53
53
|
if (!parsed.success) {
|
|
54
54
|
return err(failure("tool_error", `github POST ${path}: unexpected answer`));
|
|
55
55
|
}
|
|
56
|
-
holdToken(app, parsed.data.token, parsed.data.expires_at);
|
|
57
|
-
return ok(parsed.data.token);
|
|
56
|
+
return ok(holdToken(app, parsed.data.token, parsed.data.expires_at));
|
|
58
57
|
}
|
|
59
58
|
/** The `authorization` of a call: `GITHUB_TOKEN` as a token, or with `[extensions.github] app` set, an installation token of that App, `GITHUB_TOKEN` then holding the App's private key. A secret read outside the call is a bug and throws before the request. */
|
|
60
59
|
async function authorizationOf(ctx) {
|
|
@@ -62,7 +61,20 @@ async function authorizationOf(ctx) {
|
|
|
62
61
|
if (app === undefined)
|
|
63
62
|
return ok(`Bearer ${ctx.secrets.get(TOKEN)}`);
|
|
64
63
|
const token = await installationToken(ctx, app);
|
|
65
|
-
return token.ok ? ok(`Bearer ${token.value}`) : token;
|
|
64
|
+
return token.ok ? ok(`Bearer ${token.value.token}`) : token;
|
|
65
|
+
}
|
|
66
|
+
/** The host whose git EDGAR's own git reaches with a GitHub token. */
|
|
67
|
+
export const GIT_HOST = "github.com";
|
|
68
|
+
/** The token EDGAR's own git sends to `github.com`: with `[extensions.github] app`, an installation token and its expiry, minted or held as an API call's is; else `GITHUB_TOKEN` itself, which does not expire. */
|
|
69
|
+
export async function gitToken(ctx, host) {
|
|
70
|
+
if (host !== GIT_HOST) {
|
|
71
|
+
return err(permanentFailure("invalid", `the GitHub extension mints git tokens for ${GIT_HOST}, not ${host}`));
|
|
72
|
+
}
|
|
73
|
+
const app = config.safeParse(ctx.config ?? {}).data?.app;
|
|
74
|
+
if (app === undefined)
|
|
75
|
+
return ok({ token: ctx.secrets.get(TOKEN), expires_at_ms: null });
|
|
76
|
+
const token = await installationToken(ctx, app);
|
|
77
|
+
return token.ok ? ok({ token: token.value.token, expires_at_ms: token.value.expiresAt }) : token;
|
|
66
78
|
}
|
|
67
79
|
/** Calls the GitHub REST API and parses the answer with `schema`. */
|
|
68
80
|
export async function github(ctx, method, path, schema, body) {
|
package/dist/src/index.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { defineExtension, defineService } from "@kana-ai/edgar-sdk";
|
|
2
|
-
import { HOST, LOG_HOSTS, TOKEN, apiAccess } from "#api/client";
|
|
1
|
+
import { defineExtension, defineGitCredential, defineService } from "@kana-ai/edgar-sdk";
|
|
2
|
+
import { HOST, LOG_HOSTS, TOKEN, apiAccess, gitToken } from "#api/client";
|
|
3
3
|
import { serve } from "#feed/service";
|
|
4
4
|
import { config } from "#schemas/config";
|
|
5
5
|
import { alertTools } from "#tools/alerts";
|
|
@@ -44,6 +44,7 @@ export default defineExtension({
|
|
|
44
44
|
workflows: ["workflows/resume.toml"],
|
|
45
45
|
roles: ["agents/dismiss"],
|
|
46
46
|
service: defineService({ ...apiAccess, run: serve }),
|
|
47
|
+
gitCredential: defineGitCredential({ ...apiAccess, token: gitToken }),
|
|
47
48
|
executables: {
|
|
48
49
|
requires: [
|
|
49
50
|
{
|
package/edgar-extension.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"contract": 1,
|
|
3
3
|
"name": "github",
|
|
4
|
-
"version": "0.1.
|
|
4
|
+
"version": "0.1.2",
|
|
5
5
|
"config_schema": "schemas/config.json",
|
|
6
6
|
"secrets": [
|
|
7
7
|
{
|
|
@@ -495,6 +495,10 @@
|
|
|
495
495
|
"secrets": ["GITHUB_TOKEN"],
|
|
496
496
|
"capabilities": ["network:api.github.com"]
|
|
497
497
|
},
|
|
498
|
+
"git_credential": {
|
|
499
|
+
"secrets": ["GITHUB_TOKEN"],
|
|
500
|
+
"capabilities": ["network:api.github.com"]
|
|
501
|
+
},
|
|
498
502
|
"executables": {
|
|
499
503
|
"requires": [
|
|
500
504
|
{
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kana-ai/edgar-ext-github",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"description": "EDGAR extension for GitHub: push edgar/ branches, open, watch, close and merge pull requests, and track GitHub issues as cards.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
@@ -23,8 +23,8 @@
|
|
|
23
23
|
".": "./dist/src/index.js"
|
|
24
24
|
},
|
|
25
25
|
"dependencies": {
|
|
26
|
-
"@kana-ai/edgar-contracts": "0.1.
|
|
27
|
-
"@kana-ai/edgar-sdk": "0.1.
|
|
26
|
+
"@kana-ai/edgar-contracts": "0.1.2",
|
|
27
|
+
"@kana-ai/edgar-sdk": "0.1.2",
|
|
28
28
|
"zod": "4.6.7"
|
|
29
29
|
},
|
|
30
30
|
"devDependencies": {
|