@samebase/alchemy-kit 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.
Files changed (2) hide show
  1. package/README.md +108 -39
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,55 +1,68 @@
1
1
  # @samebase/alchemy-kit
2
2
 
3
- Parts for [Alchemy v2](https://alchemy.run). Each part is its own entry, such as
4
- `@samebase/alchemy-kit/github-state`.
3
+ [![npm](https://img.shields.io/npm/v/@samebase/alchemy-kit)](https://www.npmjs.com/package/@samebase/alchemy-kit)
4
+ [![license](https://img.shields.io/npm/l/@samebase/alchemy-kit)](https://github.com/samebase/samebase/blob/main/packages/alchemy-kit/LICENSE)
5
+
6
+ Parts for [Alchemy v2](https://alchemy.run). Each part is its own entry, so your stack loads only
7
+ the part that it imports.
8
+
9
+ | Part | Entry | What it is |
10
+ | ----------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------- |
11
+ | [GitHub state store](#github-state-store) | `@samebase/alchemy-kit/github-state` | The state of a stack on a branch of its GitHub repository, secrets sealed. |
12
+
13
+ > The source is in
14
+ > [`packages/alchemy-kit`](https://github.com/samebase/samebase/tree/main/packages/alchemy-kit) of
15
+ > the Samebase monorepo. Use [GitHub Issues](https://github.com/samebase/samebase/issues) to report
16
+ > a problem or request a change.
5
17
 
6
18
  ## GitHub state store
7
19
 
8
- An [Alchemy v2](https://alchemy.run) state store on a branch of your GitHub repository. Each
9
- resource is one JSON file on the branch. Each secret in it is sealed with AES-256-GCM under a key
10
- that you keep as a secret. You need no cloud account for the state: the repository and its
11
- `GITHUB_TOKEN` are enough.
20
+ <picture>
21
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/samebase/samebase/main/packages/alchemy-kit/docs/github-state-dark.svg">
22
+ <img src="https://raw.githubusercontent.com/samebase/samebase/main/packages/alchemy-kit/docs/github-state-light.svg" alt="A deploy, on your laptop or in GitHub Actions, holds the key ALCHEMY_GITHUB_STATE_KEY and seals each secret before it leaves the run. In your GitHub repository, the deploy takes the lock on the branch alchemy-state-store-lock, then reads and commits the state on the branch alchemy-state-store: one JSON file for each resource. The branch main holds your code and alchemy.run.ts." width="100%">
23
+ </picture>
12
24
 
13
- The sealing is the package's own until Alchemy releases state encryption
14
- ([alchemy-run/alchemy#3167](https://github.com/alchemy-run/alchemy/pull/3167)).
25
+ Alchemy keeps a record of each resource that it deployed. This store keeps that record on a branch
26
+ of the repository that the stack deploys from. The state needs no cloud account and no server: the
27
+ repository and its `GITHUB_TOKEN` are enough.
15
28
 
16
- ### Install
29
+ - **One JSON file for each resource.** You read the state on github.com, and each deploy is a commit
30
+ that names what it changed.
31
+ - **Sealed secrets.** Each secret is sealed with AES-256-GCM before it leaves the run. The key is a
32
+ repository secret.
33
+ - **One deploy of a stage at a time.** A second deploy of the same stage fails at once.
34
+
35
+ ### Quick start
36
+
37
+ **1. Install.**
17
38
 
18
39
  ```sh
19
40
  pnpm add -D @samebase/alchemy-kit alchemy@2.0.0-beta.85 effect
20
41
  ```
21
42
 
22
- ### Use
23
-
24
- In `alchemy.run.ts`:
43
+ **2. Give the store to your stack**, in `alchemy.run.ts`:
25
44
 
26
45
  ```ts
27
46
  import * as GitHubState from "@samebase/alchemy-kit/github-state";
28
-
29
- export default Alchemy.Stack("my-app", { providers, state: GitHubState.state() }, program);
47
+ import * as Alchemy from "alchemy";
48
+
49
+ export default Alchemy.Stack(
50
+ "my-app",
51
+ {
52
+ providers,
53
+ state: GitHubState.state(),
54
+ },
55
+ program,
56
+ );
30
57
  ```
31
58
 
32
- Options, all optional:
33
-
34
- - `repository`: `owner/name`. The default is `GITHUB_REPOSITORY`, else the `origin` remote.
35
- - `branch`: the state branch. The default is `alchemy-state-store`.
36
- - `key`: a `Redacted` key. The default is the environment variable `ALCHEMY_GITHUB_STATE_KEY`.
37
-
38
- The token is `GITHUB_TOKEN` or `GH_TOKEN`. It needs write access to the contents of the repository.
39
-
40
- ### The key
41
-
42
- Make the key once and keep it as the repository secret `ALCHEMY_GITHUB_STATE_KEY`:
59
+ **3. Make the key**, once, and keep it as a repository secret:
43
60
 
44
61
  ```sh
45
62
  openssl rand -base64 32 | gh secret set ALCHEMY_GITHUB_STATE_KEY
46
63
  ```
47
64
 
48
- Without the key, the store stops before it reads or writes anything. With a different key, it stops
49
- at the first secret that does not open. If you lose the key, you cannot open the secrets on the
50
- branch.
51
-
52
- ### GitHub Actions
65
+ **4. Deploy from GitHub Actions.** The job needs write access to the contents of the repository:
53
66
 
54
67
  ```yaml
55
68
  permissions:
@@ -67,7 +80,45 @@ jobs:
67
80
  ALCHEMY_GITHUB_STATE_KEY: ${{ secrets.ALCHEMY_GITHUB_STATE_KEY }}
68
81
  ```
69
82
 
70
- ### The branch
83
+ The first deploy makes the two branches.
84
+
85
+ ### Options
86
+
87
+ `GitHubState.state()` takes one object. Each field is optional.
88
+
89
+ | Option | Default | What it is |
90
+ | ------------ | --------------------------------------------------- | ------------------------------------------------------------ |
91
+ | `repository` | `GITHUB_REPOSITORY`, else the `origin` remote | The repository, as `owner/name`. |
92
+ | `branch` | `alchemy-state-store` | The state branch. The lock branch is this name with `-lock`. |
93
+ | `key` | The environment variable `ALCHEMY_GITHUB_STATE_KEY` | The key, as a `Redacted` string. |
94
+
95
+ The token is `GITHUB_TOKEN`, else `GH_TOKEN`.
96
+
97
+ ### The key
98
+
99
+ The key is 32 random bytes in base64. Each deploy of the repository uses the same key.
100
+
101
+ - Without the key, the store stops before it reads or writes anything.
102
+ - With a different key, the store stops at the first secret that does not open.
103
+ - If you lose the key, you cannot open the secrets on the branch.
104
+
105
+ The sealing is the package's own until Alchemy releases state encryption
106
+ ([alchemy-run/alchemy#3167](https://github.com/alchemy-run/alchemy/pull/3167)).
107
+
108
+ ### From your laptop
109
+
110
+ The store reads the token and the key from the environment of the process. A `.env` file does not
111
+ set them. Keep the key in a file that git ignores, here `.state-key`.
112
+
113
+ ```sh
114
+ export GITHUB_TOKEN="$(gh auth token)"
115
+ export ALCHEMY_GITHUB_STATE_KEY="$(cat .state-key)"
116
+ pnpm exec alchemy deploy --stage dev-me
117
+ ```
118
+
119
+ For a `dev-` stage that only you use, Alchemy's local state is simpler.
120
+
121
+ ### What is on the branches
71
122
 
72
123
  ```
73
124
  alchemy-state-store the state
@@ -79,14 +130,32 @@ alchemy-state-store-lock the deploy lock of each stage
79
130
  {stack}/{stage}/__lease__.json
80
131
  ```
81
132
 
82
- Both are orphan branches, made with a README on the first write. A secret in a file is
83
- `{"__redacted__": {"__sealed__": "v1.<iv>.<ciphertext>"}}`; every other value is plain JSON. A
84
- sealed value opens only in the file that it was sealed for.
133
+ Both are orphan branches: they share no history with your code. A resource file is plain JSON,
134
+ except its secrets. This is `my-app/prod/ApiKey.json`, shortened:
135
+
136
+ ```json
137
+ {
138
+ "status": "created",
139
+ "resourceType": "Alchemy.Random",
140
+ "props": { "bytes": 16 },
141
+ "attr": {
142
+ "text": {
143
+ "__redacted__": { "__sealed__": "v1.<iv>.<ciphertext>" }
144
+ }
145
+ }
146
+ }
147
+ ```
148
+
149
+ A sealed value opens only in the file that it was sealed for. A copy in a different file does not
150
+ open.
151
+
152
+ ### How a deploy writes
85
153
 
86
- All the writes that are waiting go into one commit, with a message such as
87
- `my-app prod: set Worker, Bucket`. When another deploy moved the branch first, the store reads the
88
- new head and tries again. A second deploy of the same stage fails at once while the first holds the
89
- lock.
154
+ - The deploy takes the lock of its stage and renews it while it runs. If the deploy stops without a
155
+ release, the lock ends after 60 seconds.
156
+ - All the writes that are waiting go into one commit, with a message such as
157
+ `my-app prod: set Worker, Bucket`.
158
+ - When another deploy moved the branch first, the store reads the new head and tries again.
90
159
 
91
160
  ### Limits
92
161
 
@@ -99,4 +168,4 @@ lock.
99
168
  - In a public repository, the state is public, except the sealed secrets.
100
169
  - A ruleset that requires pull requests on all branches, or a tool that deletes stale branches,
101
170
  breaks the store. Keep both branches out of such rules.
102
- - A laptop deploy needs the key and a token. For `dev-` stages, local state is simpler.
171
+ - There is no key rotation. A new key cannot open the secrets that the old key sealed.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@samebase/alchemy-kit",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "A kit of parts for Alchemy v2: a state store on a branch of a GitHub repository, with sealed secrets",
5
5
  "keywords": [
6
6
  "alchemy",