diff --git a/Services.md b/Services.md index f3bc707..86e9a34 100644 --- a/Services.md +++ b/Services.md @@ -130,6 +130,42 @@ Service tags generally follow these rules: These rules are not exhaustive and should only be used as a guide. You don't strictly have to follow these rules, but we recommend doing so for consistency. +## Cookies & Credentials + +unshackle can authenticate with Services using Cookies and/or Credentials. Credentials are stored in the config, and +Cookies are stored in the data directory which can be found by running `unshackle env info`. + +To add a Credential to a Service, take a look at the [Credentials Config](CONFIG.md#credentials-dictstr-strlistdict) +for information on setting up one or more credentials per-service. You can add one or more Credential per-service and +use `-p/--profile` to choose which Credential to use. + +To add a Cookie to a Service, use a Cookie file extension to make a `cookies.txt` file and move it into the Cookies +directory. You must rename the `cookies.txt` file to that of the Service tag (case-sensitive), e.g., `NF.txt`. You can +also place it in a Service Cookie folder, e.g., `/Cookies/NF/default.txt` or `/Cookies/NF/.txt`. + +You can add multiple Cookies to the `/Cookies/NF/` folder with their own unique name and then use `-p/--profile` to +choose which one to use. E.g., `/Cookies/NF/sam.txt` and then use it with `--profile sam`. If you make a Service Cookie +folder without a `.txt` or `default.txt`, but with another file, then no Cookies will be loaded unless you use +`-p/--profile` like shown. This allows you to opt in to authentication at whim. + +> - If your Service does not require Authentication, then do not define any Credential or Cookie for that Service. +> - You can use both Cookies and Credentials at the same time, so long as your Service takes and uses both. +> - If you are using profiles, then make sure you use the same name on the Credential name and Cookie file name when +> using `-p/--profile`. +> [!WARNING] +> Profile names are case-sensitive and unique per-service. They have no arbitrary character or length limit, but for +> convenience sake we don't recommend using any special characters as your terminal may get confused. + +### Cookie file format and Extensions + +Cookies must be in the standard Netscape cookies file format. +Recommended Cookie exporter extensions: + +- Firefox: "[Export Cookies]" by `Rotem Dan` +- Chromium: "[Open Cookies.txt]" by `Ninh Pham` + +Any other extension that exports to the standard Netscape format should theoretically work. + ### Sharing Services Sending and receiving zipped Service folders is quite cumbersome. Let's explore alternative routes to collaborating on