@aomex-contrib/oauth2-github 0.0.0-stage → 0.1.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/CHANGELOG.md ADDED
@@ -0,0 +1,15 @@
1
+ # @aomex-contrib/oauth2-github
2
+
3
+ ## 0.1.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [`013319f`](https://github.com/aomex/aomex-contrib/commit/013319f96e95278a693f55708798733412f0a947) Thanks [@geekact](https://github.com/geekact)! - 新增厂商 OAuth2 / OIDC 客户端包:Google、Microsoft、Apple、GitHub、Discord、GitLab、LinkedIn、Facebook、Twitter(X)、Spotify。
8
+
9
+ - 纯 OAuth2 厂商默认 `callback` 返回 `{ base, userinfo }`
10
+ - Apple:`form_post` + JWT `client_secret`;默认 profile 为 `{ claims, user }`(`user` 仅首次授权可能有姓名)
11
+
12
+ ### Patch Changes
13
+
14
+ - Updated dependencies [[`013319f`](https://github.com/aomex/aomex-contrib/commit/013319f96e95278a693f55708798733412f0a947)]:
15
+ - @aomex-contrib/oauth2-preset@0.1.0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2023-2024 geekact
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,129 @@
1
- # Temporary Holding Version
1
+ # @aomex-contrib/oauth2-github
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ GitHub **OAuth App** 登录预设。默认 `callback` 拉取 [`GET /user`](https://docs.github.com/en/rest/users/users#get-the-authenticated-user),返回 `{ base, userinfo }`。
4
+
5
+ 官方文档:[Authorizing OAuth apps](https://docs.github.com/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps)。
6
+
7
+ ---
8
+
9
+ ## 1. 安装
10
+
11
+ ```bash
12
+ pnpm add @aomex-contrib/oauth2-github @aomex/oauth2-client
13
+ ```
14
+
15
+ ---
16
+
17
+ ## 2. GitHub 后台准备
18
+
19
+ 1. GitHub → Settings → Developer settings → [OAuth Apps](https://github.com/settings/developers) → New OAuth App
20
+ 2. 填写:
21
+ - Application name
22
+ - Homepage URL:如 `https://example.com`
23
+ - **Authorization callback URL**:`https://example.com/oauth/github/callback`(须与代码一致)
24
+ 3. 创建后复制 **Client ID**,再 Generate a new client secret
25
+
26
+ | 环境变量建议 | 对应 |
27
+ | ---------------------- | ------------- |
28
+ | `GITHUB_CLIENT_ID` | Client ID |
29
+ | `GITHUB_CLIENT_SECRET` | Client secret |
30
+
31
+ 说明:这是 **OAuth App**,不是 GitHub App。若你用的是 GitHub App 用户授权,端点/流程不同,本预设按 OAuth App 编写。
32
+
33
+ ---
34
+
35
+ ## 3. store
36
+
37
+ 保存 OAuth `state`。生产多实例用 Redis 等共享 `CacheAdapter`;单机可用 `CacheMemoryAdapter`。
38
+
39
+ ---
40
+
41
+ ## 4. 最小可跑通示例
42
+
43
+ ```ts
44
+ import { CacheMemoryAdapter } from '@aomex/cache/memory';
45
+ import { GitHubOAuth2Client } from '@aomex-contrib/oauth2-github';
46
+
47
+ const github = new GitHubOAuth2Client({
48
+ clientId: process.env.GITHUB_CLIENT_ID!,
49
+ clientSecret: process.env.GITHUB_CLIENT_SECRET!,
50
+ redirectUri: 'https://example.com/oauth/github/callback',
51
+ store: new CacheMemoryAdapter(),
52
+ // 默认 scopes: read:user, user:email
53
+ });
54
+
55
+ router.get('/oauth/github', {
56
+ action: async (ctx) => {
57
+ await github.redirect(ctx);
58
+ },
59
+ });
60
+
61
+ router.get('/oauth/github/callback', {
62
+ action: async (ctx) => {
63
+ const profile = await github.callback(ctx);
64
+ // profile.base = 令牌;profile.userinfo = GitHubUser
65
+ ctx.send(profile);
66
+ },
67
+ });
68
+ ```
69
+
70
+ ### 流程
71
+
72
+ 1. `/oauth/github` → 302 到 GitHub 授权页
73
+ 2. 用户同意 → 回到回调带 `code` + `state`
74
+ 3. 换票 → 默认请求 `https://api.github.com/user` → 返回 `{ base, userinfo: GitHubUser }`
75
+ 4. 你自己写登录态
76
+
77
+ ---
78
+
79
+ ## 5. 默认返回什么
80
+
81
+ 默认 `callback` 返回:
82
+
83
+ ```ts
84
+ {
85
+ base: TokenSet; // access_token 等
86
+ userinfo: GitHubUser; // 来自 `GET /user`
87
+ }
88
+ ```
89
+
90
+ `GitHubUser` 常见字段:`id`、`login`、`name`、`email`、`avatar_url`、`html_url`。
91
+
92
+ 自定义 `onProfile` 时框架已拉好 `userinfo`:
93
+
94
+ ```ts
95
+ onProfile: async ({ token, userinfo }) => {
96
+ return upsertUser({ id: userinfo.id /* 或对应字段 */ });
97
+ },
98
+ ```
99
+
100
+ 也可直接:`import { fetchGitHubUser, github } from '@aomex-contrib/oauth2-github'`。
101
+
102
+ ---
103
+
104
+ ## 6. 默认预设
105
+
106
+ ```ts
107
+ authorizationEndpoint: 'https://github.com/login/oauth/authorize';
108
+ tokenEndpoint: 'https://github.com/login/oauth/access_token';
109
+ scopes: ['read:user', 'user:email'];
110
+ ```
111
+
112
+ 可用构造参数 `scopes` / 端点字段覆盖(例如只要 `read:user`)。
113
+
114
+ ---
115
+
116
+ ## 7. 常见问题
117
+
118
+ **Q: redirect_uri 不匹配?**
119
+ A: OAuth App 回调 URL 与 `redirectUri` 必须一致。
120
+
121
+ **Q: email 为空?**
122
+ A: 用户隐私设置;用 `user:emails` API 或引导用户公开邮箱。
123
+
124
+ **Q: Enterprise Server?**
125
+ A: 本预设指向 github.com。自建可覆盖 `authorizationEndpoint` / `tokenEndpoint`,并自行改 `onProfile` 里的 API Host。
126
+
127
+ ---
128
+
129
+ 通用能力见:https://aomex.js.org
@@ -0,0 +1,40 @@
1
+ import { OAuth2Client } from "@aomex/oauth2-client";
2
+ import { OAuth2Profile, OAuth2Profile as OAuth2Profile$1, OAuth2VendorOnProfileArgs, OAuth2VendorOptions, OAuth2VendorOptions as OAuth2VendorOptions$1 } from "@aomex-contrib/oauth2-preset";
3
+ /**
4
+ * GitHub OAuth2 客户端预设
5
+ * @see https://docs.github.com/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps
6
+ */
7
+ export declare const github: {
8
+ readonly authorizationEndpoint: 'https://github.com/login/oauth/authorize';
9
+ readonly tokenEndpoint: 'https://github.com/login/oauth/access_token';
10
+ readonly scopes: readonly ['read:user', 'user:email'];
11
+ };
12
+ /**
13
+ * `GET https://api.github.com/user` 常见字段
14
+ * @see https://docs.github.com/en/rest/users/users#get-the-authenticated-user
15
+ */
16
+ export type GitHubUser = {
17
+ /** 用户数字 ID */
18
+ id: number;
19
+ /** 用户名(login) */
20
+ login: string;
21
+ /** 显示名;未设置时为 `null` */
22
+ name: string | null;
23
+ /**
24
+ * 公开主邮箱;用户隐藏邮箱时可能为 `null`。
25
+ * 需要完整邮箱列表时可另调 `/user/emails`
26
+ */
27
+ email: string | null;
28
+ /** 头像 URL */
29
+ avatar_url: string;
30
+ /** 用户主页 URL */
31
+ html_url: string;
32
+ };
33
+ export declare function fetchGitHubUser(accessToken: string): Promise<GitHubUser>;
34
+ /**
35
+ * GitHub OAuth2 客户端;默认 `callback` 返回 `{ base, userinfo }`(`userinfo` 来自 `/user`)
36
+ */
37
+ export declare class GitHubOAuth2Client<Profile = OAuth2Profile$1<GitHubUser>> extends OAuth2Client<Profile> {
38
+ constructor(opts: OAuth2VendorOptions$1<Profile, GitHubUser>);
39
+ }
40
+ export type { OAuth2Profile, OAuth2VendorOnProfileArgs, OAuth2VendorOptions };
package/dist/index.js ADDED
@@ -0,0 +1,31 @@
1
+ import { OAuth2Client } from "@aomex/oauth2-client";
2
+ import { mergeOAuth2Preset } from "@aomex-contrib/oauth2-preset";
3
+ // src/index.ts
4
+ /**
5
+ * GitHub OAuth2 客户端预设
6
+ * @see https://docs.github.com/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps
7
+ */
8
+ const github = {
9
+ authorizationEndpoint: "https://github.com/login/oauth/authorize",
10
+ tokenEndpoint: "https://github.com/login/oauth/access_token",
11
+ scopes: ["read:user", "user:email"]
12
+ };
13
+ async function fetchGitHubUser(accessToken) {
14
+ const res = await fetch("https://api.github.com/user", { headers: {
15
+ Authorization: `Bearer ${accessToken}`,
16
+ Accept: "application/vnd.github+json"
17
+ } });
18
+ if (!res.ok) throw new Error(`GitHub /user failed: ${res.status}`);
19
+ return await res.json();
20
+ }
21
+ /**
22
+ * GitHub OAuth2 客户端;默认 `callback` 返回 `{ base, userinfo }`(`userinfo` 来自 `/user`)
23
+ */
24
+ var GitHubOAuth2Client = class extends OAuth2Client {
25
+ constructor(opts) {
26
+ super(mergeOAuth2Preset(github, opts, fetchGitHubUser));
27
+ }
28
+ };
29
+ export { GitHubOAuth2Client, fetchGitHubUser, github };
30
+
31
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import { OAuth2Client } from '@aomex/oauth2-client';\nimport {\n mergeOAuth2Preset,\n type OAuth2Profile,\n type OAuth2VendorOptions,\n} from '@aomex-contrib/oauth2-preset';\n\n/**\n * GitHub OAuth2 客户端预设\n * @see https://docs.github.com/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps\n */\nexport const github = {\n authorizationEndpoint: 'https://github.com/login/oauth/authorize',\n tokenEndpoint: 'https://github.com/login/oauth/access_token',\n scopes: ['read:user', 'user:email'],\n} as const;\n\n/**\n * `GET https://api.github.com/user` 常见字段\n * @see https://docs.github.com/en/rest/users/users#get-the-authenticated-user\n */\nexport type GitHubUser = {\n /** 用户数字 ID */\n id: number;\n /** 用户名(login) */\n login: string;\n /** 显示名;未设置时为 `null` */\n name: string | null;\n /**\n * 公开主邮箱;用户隐藏邮箱时可能为 `null`。\n * 需要完整邮箱列表时可另调 `/user/emails`\n */\n email: string | null;\n /** 头像 URL */\n avatar_url: string;\n /** 用户主页 URL */\n html_url: string;\n};\n\nexport async function fetchGitHubUser(accessToken: string): Promise<GitHubUser> {\n const res = await fetch('https://api.github.com/user', {\n headers: {\n Authorization: `Bearer ${accessToken}`,\n Accept: 'application/vnd.github+json',\n },\n });\n if (!res.ok) {\n throw new Error(`GitHub /user failed: ${res.status}`);\n }\n return (await res.json()) as GitHubUser;\n}\n\n/**\n * GitHub OAuth2 客户端;默认 `callback` 返回 `{ base, userinfo }`(`userinfo` 来自 `/user`)\n */\nexport class GitHubOAuth2Client<\n Profile = OAuth2Profile<GitHubUser>,\n> extends OAuth2Client<Profile> {\n constructor(opts: OAuth2VendorOptions<Profile, GitHubUser>) {\n super(mergeOAuth2Preset(github, opts, fetchGitHubUser));\n }\n}\n\nexport type {\n OAuth2Profile,\n OAuth2VendorOptions,\n OAuth2VendorOnProfileArgs,\n} from '@aomex-contrib/oauth2-preset';\n"],"mappings":";;;;;;;AAWA,MAAa,SAAS;CACpB,uBAAuB;CACvB,eAAe;CACf,QAAQ,CAAC,aAAa,YAAY;AACpC;AAwBA,eAAsB,gBAAgB,aAA0C;CAC9E,MAAM,MAAM,MAAM,MAAM,+BAA+B,EACrD,SAAS;EACP,eAAe,UAAU;EACzB,QAAQ;CACV,EACF,CAAC;CACD,IAAI,CAAC,IAAI,IACP,MAAM,IAAI,MAAM,wBAAwB,IAAI,QAAQ;CAEtD,OAAQ,MAAM,IAAI,KAAK;AACzB;;;;AAKA,IAAa,qBAAb,cAEU,aAAsB;CAC9B,YAAY,MAAgD;EAC1D,MAAM,kBAAkB,QAAQ,MAAM,eAAe,CAAC;CACxD;AACF"}
package/package.json CHANGED
@@ -1,6 +1,44 @@
1
1
  {
2
2
  "name": "@aomex-contrib/oauth2-github",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0",
4
+ "description": "GitHub OAuth2 客户端预设",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git@github.com:aomex/aomex-contrib.git"
8
+ },
9
+ "homepage": "https://aomex.js.org",
10
+ "license": "MIT",
11
+ "type": "module",
12
+ "sideEffects": false,
13
+ "types": "dist/index.d.ts",
14
+ "exports": {
15
+ ".": {
16
+ "types": "./dist/index.d.ts",
17
+ "import": "./dist/index.js"
18
+ },
19
+ "./package.json": "./package.json"
20
+ },
21
+ "files": [
22
+ "dist",
23
+ "LICENSE",
24
+ "package.json",
25
+ "README.md",
26
+ "CHANGELOG.md"
27
+ ],
28
+ "publishConfig": {
29
+ "access": "public"
30
+ },
31
+ "peerDependencies": {
32
+ "@aomex/oauth2-client": "^4.3.0"
33
+ },
34
+ "dependencies": {
35
+ "@aomex-contrib/oauth2-preset": "^0.1.0"
36
+ },
37
+ "devDependencies": {
38
+ "@aomex/cache": "^4.3.0",
39
+ "@aomex/common": "^4.3.0",
40
+ "@aomex/oauth2-client": "^4.3.0",
41
+ "@aomex/web": "^4.3.0"
42
+ },
43
+ "scripts": {}
6
44
  }